GRASS GIS 8 Programmer's Manual  8.2.1dev(2022)-31a672db8
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 *,
21  const char *, 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,
62  const char *element, const char *name, 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., "history", "REF")
96  \param name name of object (raster, group; fully qualified names allowed e.g., "my_raster@PERMANENT")
97  \param mapset mapset name
98 
99  \return pointer to <i>path</i> buffer
100 */
101 char *G_file_name_misc(char *path,
102  const char *dir,
103  const char *element,
104  const char *name, const char *mapset)
105 {
106  return file_name(path, dir, element, name, mapset, NULL);
107 }
108 
109 /*!
110  \brief Builds full path names to GIS data files in temporary directory (for internal use only)
111 
112  By default temporary directory is located
113  $LOCATION/$MAPSET/.tmp/$HOSTNAME. If GRASS_VECTOR_TMPDIR_MAPSET is
114  set to "0", the temporary directory is located in TMPDIR
115  (environmental variable defined by the user or GRASS initialization
116  script if not given). Note that GRASS_VECTOR_TMPDIR_MAPSET variable
117  is currently used only by vector library.
118 
119  \param[out] path buffer to hold resultant full path to file
120  \param element database element (eg, "cell", "cellhd", "vector", etc)
121  \param name name of file to build path to (fully qualified names allowed)
122  \param mapset mapset name
123 
124  \return pointer to <i>path</i> buffer
125 */
126 char *G_file_name_tmp(char *path,
127  const char *element,
128  const char *name, const char *mapset)
129 {
130  const char *env, *tmp_path;
131 
132  tmp_path = NULL;
133  env = getenv("GRASS_VECTOR_TMPDIR_MAPSET");
134  if (env && strcmp(env, "0") == 0) {
135  tmp_path = getenv("TMPDIR");
136  }
137 
138  return file_name(path, NULL, element, name, mapset, tmp_path);
139 }
140 
141 char *file_name(char *path,
142  const char *dir, const char *element, const char *name,
143  const char *mapset, const char *base)
144 {
145  const char *pname = name;
146 
147  if (base && *base) {
148  sprintf(path, "%s", base);
149  }
150  else {
151  char xname[GNAME_MAX];
152  char xmapset[GMAPSET_MAX];
153  char *location = G__location_path();
154 
155  /*
156  * if a name is given, build a file name
157  * must split the name into name, mapset if it is
158  * in the name@mapset format
159  */
160  if (name && *name && G_name_is_fully_qualified(name, xname, xmapset)) {
161  pname = xname;
162  sprintf(path, "%s%c%s", location, HOST_DIRSEP, xmapset);
163  }
164  else if (mapset && *mapset)
165  sprintf(path, "%s%c%s", location, HOST_DIRSEP, mapset);
166  else
167  sprintf(path, "%s%c%s", location, HOST_DIRSEP, G_mapset());
168  G_free(location);
169  }
170 
171  if (dir && *dir) { /* misc element */
172  append_char(path, HOST_DIRSEP);
173  strcat(path, dir);
174 
175  if (pname && *pname) {
176  append_char(path, HOST_DIRSEP);
177  strcat(path, pname);
178  }
179 
180  if (element && *element) {
181  append_char(path, HOST_DIRSEP);
182  strcat(path, element);
183  }
184  }
185  else {
186  if (element && *element) {
187  append_char(path, HOST_DIRSEP);
188  strcat(path, element);
189  }
190 
191  if (pname && *pname) {
192  append_char(path, HOST_DIRSEP);
193  strcat(path, pname);
194  }
195  }
196 
197  G_debug(2, "G_file_name(): path = %s", path);
198 
199  return path;
200 }
201 
202 void append_char(char* s, char c)
203 {
204  int len = strlen(s);
205  s[len] = c;
206  s[len+1] = '\0';
207 }
#define GMAPSET_MAX
Definition: gis.h:178
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:126
void G_free(void *)
Free allocated memory.
Definition: gis/alloc.c:149
char * G__location_path(void)
Get current location UNIX-like path (internal use only)
Definition: location.c:78
#define NULL
Definition: ccmath.h:32
Definition: lidar.h:86
#define HOST_DIRSEP
Definition: gis.h:223
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
const char * G_mapset(void)
Get current mapset name.
Definition: gis/mapset.c:33
#define GNAME_MAX
Definition: gis.h:177
Definition: path.h:16
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
const char * name
Definition: named_colr.c:7
char * getenv()
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
int G_debug(int, const char *,...) __attribute__((format(printf