GRASS GIS 8 Programmer's Manual  8.5.0dev(2025)-b35369f6b7
All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
file_name.c
Go to the documentation of this file.
1 /*!
2  \file lib/gis/file_name.c
3 
4  \brief GIS library - Determine GRASS data base file name
5 
6  (C) 2001-2015 by the GRASS Development Team
7 
8  This program is free software under the GNU General Public License
9  (>=v2). Read the file COPYING that comes with GRASS for details.
10 
11  \author Original author CERL
12  */
13 
14 #include <string.h>
15 #include <stdlib.h>
16 #include <grass/gis.h>
17 
18 #include "gis_local_proto.h"
19 
20 static char *file_name(char *, const char *, const char *, const char *,
21  const char *, const char *);
22 static void append_char(char *, char);
23 
24 /*!
25  \brief Builds full path names to GIS data files
26 
27  If <i>name</i> is of the form "nnn@ppp" then path is set as if name
28  had been "nnn" and mapset had been "ppp" (mapset parameter itself is
29  ignored in this case).
30 
31  Paths to files are currently in form:
32  /path/to/location/mapset/element/name
33 
34  path input buffer memory must be allocated by caller.
35 
36  C:
37  @code{.c}
38  char path[GPATH_MAX];
39  G_file_name(path, "fcell", "my_raster", "my_mapset");
40  // path now is "/full/path/to/my_mapset/fcell/my_raster"
41  @endcode
42  Python:
43  @code{.py}
44  import ctypes
45  from grass.pygrass.utils import decode
46  from grass.lib.gis import G_file_name, GPATH_MAX
47 
48  path = ctypes.create_string_buffer(GPATH_MAX)
49  path_str = decode(G_file_name(path, "elem", "name", "mapset"))
50  print(path_str)
51  >>> /full/path/to/mapset/elem/name
52  @endcode
53 
54  \param[out] path allocated buffer to hold resultant full path to file
55  \param element database element (eg, "cell", "cellhd", "vector", etc)
56  \param name name of file to build path to (fully qualified names allowed)
57  \param mapset mapset name
58 
59  \return pointer to <i>path</i> buffer
60  */
61 char *G_file_name(char *path, const char *element, const char *name,
62  const char *mapset)
63 {
64  return file_name(path, NULL, element, name, mapset, NULL);
65 }
66 
67 /*!
68  \brief Builds full path names to GIS misc data files
69 
70  Paths to misc files are currently in form:
71  /path/to/location/mapset/dir/name/element
72 
73  path input buffer memory must be allocated by caller.
74 
75  C:
76  @code{.c}
77  char path[GPATH_MAX];
78  G_file_name_misc(path, "cell_misc", "history", "my_raster", "my_mapset");
79  // path now contains "/full/path/to/my_mapset/cell_misc/my_raster/history"
80  @endcode
81  Python:
82  @code{.py}
83  import ctypes
84  from grass.pygrass.utils import decode
85  from grass.lib.gis import G_file_name_misc, GPATH_MAX
86 
87  path = ctypes.create_string_buffer(GPATH_MAX)
88  path_str = decode(G_file_name_misc(path, "dir", "elem", "name", "mapset"))
89  print(path_str)
90  >>> /full/path/to/mapset/dir/name/elem
91  @endcode
92 
93  \param[out] path allocated buffer to hold resultant full path to file
94  \param dir misc directory (e.g., "cell_misc", "group")
95  \param element database element (in this case – file to build path to e.g.,
96  "history", "REF") \param name name of object (raster, group; fully qualified
97  names allowed e.g., "my_raster@PERMANENT") \param mapset mapset name
98 
99  \return pointer to <i>path</i> buffer
100  */
101 char *G_file_name_misc(char *path, const char *dir, const char *element,
102  const char *name, const char *mapset)
103 {
104  return file_name(path, dir, element, name, mapset, NULL);
105 }
106 
107 /*!
108  \brief Builds full path names to GIS data files in temporary directory (for
109  internal use only)
110 
111  By default temporary directory is located
112  $LOCATION/$MAPSET/.tmp/$HOSTNAME. If GRASS_VECTOR_TMPDIR_MAPSET is
113  set to "0", the temporary directory is located in TMPDIR
114  (environmental variable defined by the user or GRASS initialization
115  script if not given). Note that GRASS_VECTOR_TMPDIR_MAPSET variable
116  is currently used only by vector library.
117 
118  \param[out] path buffer to hold resultant full path to file
119  \param element database element (eg, "cell", "cellhd", "vector", etc)
120  \param name name of file to build path to (fully qualified names allowed)
121  \param mapset mapset name
122 
123  \return pointer to <i>path</i> buffer
124  */
125 char *G_file_name_tmp(char *path, const char *element, const char *name,
126  const char *mapset)
127 {
128  const char *env;
129  char tmp_path[GPATH_MAX] = {0};
130 
131  env = getenv("GRASS_VECTOR_TMPDIR_MAPSET");
132  if (env && strcmp(env, "0") == 0) {
133  snprintf(tmp_path, GPATH_MAX, "%s", getenv("TMPDIR"));
134  }
135 
136  return file_name(path, NULL, element, name, mapset, tmp_path);
137 }
138 
139 /*!
140  \brief Builds full path names to GIS data files in temporary directory (for
141  internal use only)
142 
143  By default the GRASS temporary directory is located at
144  $LOCATION/$MAPSET/.tmp/$HOSTNAME/. If basedir is provided, the
145  temporary directory is located at <basedir>/.tmp/$HOSTNAME/.
146 
147  \param[out] path buffer to hold resultant full path to file
148  \param element database element (eg, "cell", "cellhd", "vector", etc)
149  \param name name of file to build path to (fully qualified names allowed)
150  \param mapset mapset name
151  \param basedir
152 
153  \return pointer to <i>path</i> buffer
154  */
155 char *G_file_name_basedir(char *path, const char *element, const char *name,
156  const char *mapset, const char *basedir)
157 {
158  return file_name(path, NULL, element, name, mapset, basedir);
159 }
160 
161 char *file_name(char *path, const char *dir, const char *element,
162  const char *name, const char *mapset, const char *base)
163 {
164  const char *pname = name;
165  char xname[GNAME_MAX] = {'\0'};
166 
167  if (base && *base) {
168  sprintf(path, "%s", base);
169  }
170  else {
171  char xmapset[GMAPSET_MAX] = {'\0'};
172  char *location = G__location_path();
173 
174  /*
175  * if a name is given, build a file name
176  * must split the name into name, mapset if it is
177  * in the name@mapset format
178  */
179  if (name && *name && G_name_is_fully_qualified(name, xname, xmapset)) {
180  pname = xname;
181  sprintf(path, "%s%c%s", location, HOST_DIRSEP, xmapset);
182  }
183  else if (mapset && *mapset)
184  sprintf(path, "%s%c%s", location, HOST_DIRSEP, mapset);
185  else
186  sprintf(path, "%s%c%s", location, HOST_DIRSEP, G_mapset());
187  G_free(location);
188  }
189 
190  if (dir && *dir) { /* misc element */
191  append_char(path, HOST_DIRSEP);
192  strcat(path, dir);
193 
194  if (pname && *pname) {
195  append_char(path, HOST_DIRSEP);
196  strcat(path, pname);
197  }
198 
199  if (element && *element) {
200  append_char(path, HOST_DIRSEP);
201  strcat(path, element);
202  }
203  }
204  else {
205  if (element && *element) {
206  append_char(path, HOST_DIRSEP);
207  strcat(path, element);
208  }
209 
210  if (pname && *pname) {
211  append_char(path, HOST_DIRSEP);
212  strcat(path, pname);
213  }
214  }
215 
216  G_debug(2, "G_file_name(): path = %s", path);
217 
218  return path;
219 }
220 
221 void append_char(char *s, char c)
222 {
223  int len = strlen(s);
224 
225  s[len] = c;
226  s[len + 1] = '\0';
227 }
#define NULL
Definition: ccmath.h:32
int G_name_is_fully_qualified(const char *, char *, char *)
Check if map name is fully qualified (map @ mapset)
Definition: nme_in_mps.c:36
void G_free(void *)
Free allocated memory.
Definition: gis/alloc.c:150
const char * G_mapset(void)
Get current mapset name.
Definition: gis/mapset.c:33
int G_debug(int, const char *,...) __attribute__((format(printf
char * G_file_name_basedir(char *path, const char *element, const char *name, const char *mapset, const char *basedir)
Builds full path names to GIS data files in temporary directory (for internal use only)
Definition: file_name.c:155
char * G_file_name(char *path, const char *element, const char *name, const char *mapset)
Builds full path names to GIS data files.
Definition: file_name.c:61
char * G_file_name_tmp(char *path, const char *element, const char *name, const char *mapset)
Builds full path names to GIS data files in temporary directory (for internal use only)
Definition: file_name.c:125
char * G_file_name_misc(char *path, const char *dir, const char *element, const char *name, const char *mapset)
Builds full path names to GIS misc data files.
Definition: file_name.c:101
#define GMAPSET_MAX
Definition: gis.h:197
#define GPATH_MAX
Definition: gis.h:199
#define GNAME_MAX
Definition: gis.h:196
#define HOST_DIRSEP
Definition: gis.h:240
char * G__location_path(void)
Get current location UNIX-like path (internal use only)
Definition: location.c:77
const char * name
Definition: named_colr.c:6
Definition: lidar.h:85
Definition: path.h:15