GRASS GIS 8 Programmer's Manual 8.4.1(2025)-45ca3179ab
Loading...
Searching...
No Matches
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
20static char *file_name(char *, const char *, const char *, const char *,
21 const char *, const char *);
22static 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 */
61char *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 */
101char *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 */
125char *G_file_name_tmp(char *path, const char *element, const char *name,
126 const char *mapset)
127{
128 const char *env, *tmp_path;
129
130 tmp_path = NULL;
131 env = getenv("GRASS_VECTOR_TMPDIR_MAPSET");
132 if (env && strcmp(env, "0") == 0) {
133 tmp_path = 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
152 \return pointer to <i>path</i> buffer
153 */
154char *G_file_name_basedir(char *path, const char *element, const char *name,
155 const char *mapset, const char *basedir)
156{
157 return file_name(path, NULL, element, name, mapset, basedir);
158}
159
160char *file_name(char *path, const char *dir, const char *element,
161 const char *name, const char *mapset, const char *base)
162{
163 const char *pname = name;
164
165 if (base && *base) {
166 sprintf(path, "%s", base);
167 }
168 else {
169 char xname[GNAME_MAX];
170 char xmapset[GMAPSET_MAX];
171 char *location = G__location_path();
172
173 /*
174 * if a name is given, build a file name
175 * must split the name into name, mapset if it is
176 * in the name@mapset format
177 */
178 if (name && *name && G_name_is_fully_qualified(name, xname, xmapset)) {
179 pname = xname;
180 sprintf(path, "%s%c%s", location, HOST_DIRSEP, xmapset);
181 }
182 else if (mapset && *mapset)
183 sprintf(path, "%s%c%s", location, HOST_DIRSEP, mapset);
184 else
185 sprintf(path, "%s%c%s", location, HOST_DIRSEP, G_mapset());
186 G_free(location);
187 }
188
189 if (dir && *dir) { /* misc element */
190 append_char(path, HOST_DIRSEP);
191 strcat(path, dir);
192
193 if (pname && *pname) {
194 append_char(path, HOST_DIRSEP);
195 strcat(path, pname);
196 }
197
198 if (element && *element) {
199 append_char(path, HOST_DIRSEP);
200 strcat(path, element);
201 }
202 }
203 else {
204 if (element && *element) {
205 append_char(path, HOST_DIRSEP);
206 strcat(path, element);
207 }
208
209 if (pname && *pname) {
210 append_char(path, HOST_DIRSEP);
211 strcat(path, pname);
212 }
213 }
214
215 G_debug(2, "G_file_name(): path = %s", path);
216
217 return path;
218}
219
220void append_char(char *s, char c)
221{
222 int len = strlen(s);
223
224 s[len] = c;
225 s[len + 1] = '\0';
226}
void G_free(void *buf)
Free allocated memory.
Definition alloc.c:150
#define NULL
Definition ccmath.h:32
int G_debug(int level, const char *msg,...)
Print debugging message.
Definition debug.c:66
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_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:154
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
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__location_path(void)
Get current location UNIX-like path (internal use only)
Definition location.c:77
const char * G_mapset(void)
Get current mapset name.
Definition mapset.c:33
const char * name
Definition named_colr.c:6
int G_name_is_fully_qualified(const char *fullname, char *name, char *mapset)
Check if map name is fully qualified (map @ mapset)
Definition nme_in_mps.c:36
Definition path.h:15