/src/gdal/netcdf-c-4.7.4/libdispatch/dgroup.c
Line | Count | Source (jump to first uncovered line) |
1 | | /*! \file |
2 | | Functions for netCDF-4 features. |
3 | | |
4 | | Copyright 2018 University Corporation for Atmospheric |
5 | | Research/Unidata. See \ref copyright file for more info. */ |
6 | | |
7 | | #include "ncdispatch.h" |
8 | | |
9 | | /** \defgroup groups Groups |
10 | | |
11 | | NetCDF-4 added support for hierarchical groups within netCDF datasets. |
12 | | |
13 | | Groups are identified with a ncid, which identifies both the open |
14 | | file, and the group within that file. When a file is opened with |
15 | | nc_open or nc_create, the ncid for the root group of that file is |
16 | | provided. Using that as a starting point, users can add new groups, or |
17 | | list and navigate existing groups or rename a group. |
18 | | |
19 | | All netCDF calls take a ncid which determines where the call will take |
20 | | its action. For example, the nc_def_var function takes a ncid as its |
21 | | first parameter. It will create a variable in whichever group its ncid |
22 | | refers to. Use the root ncid provided by nc_create or nc_open to |
23 | | create a variable in the root group. Or use nc_def_grp to create a |
24 | | group and use its ncid to define a variable in the new group. |
25 | | |
26 | | Variable are only visible in the group in which they are defined. The |
27 | | same applies to attributes. “Global” attributes are associated with |
28 | | the group whose ncid is used. |
29 | | |
30 | | Dimensions are visible in their groups, and all child groups. |
31 | | |
32 | | Group operations are only permitted on netCDF-4 files - that is, files |
33 | | created with the HDF5 flag in nc_create(). Groups are not compatible |
34 | | with the netCDF classic data model, so files created with the |
35 | | ::NC_CLASSIC_MODEL file cannot contain groups (except the root group). |
36 | | |
37 | | Encoding both the open file id and group id in a single integer |
38 | | currently limits the number of groups per netCDF-4 file to no more |
39 | | than 32767. Similarly, the number of simultaneously open netCDF-4 |
40 | | files in one program context is limited to 32767. |
41 | | |
42 | | */ |
43 | | |
44 | | /** \{*/ /* All these functions are part of the above defgroup... */ |
45 | | |
46 | | /*! Return the group ID for a group given the name. |
47 | | |
48 | | |
49 | | @param[in] ncid A valid file or group ncid. |
50 | | @param[in] name The name of the group you are querying. |
51 | | @param[out] grp_ncid Pointer to memory to hold the group ncid. |
52 | | |
53 | | @returns Error code or ::NC_NOERR or no error. |
54 | | |
55 | | */ |
56 | | int nc_inq_ncid(int ncid, const char *name, int *grp_ncid) |
57 | 63 | { |
58 | 63 | NC* ncp; |
59 | 63 | int stat = NC_check_id(ncid,&ncp); |
60 | 63 | if(stat != NC_NOERR) return stat; |
61 | 63 | return ncp->dispatch->inq_ncid(ncid,name,grp_ncid); |
62 | 63 | } |
63 | | |
64 | | /*! Get a list of groups or subgroups from a file or groupID. |
65 | | |
66 | | @param[in] ncid The ncid of the file or parent group. |
67 | | @param[out] numgrps Pointer to memory to hold the number of groups. |
68 | | @param[out] ncids Pointer to memory to hold the ncid for each group. |
69 | | |
70 | | @returns Error code or ::NC_NOERR for no error. |
71 | | |
72 | | */ |
73 | | int nc_inq_grps(int ncid, int *numgrps, int *ncids) |
74 | 1.41M | { |
75 | 1.41M | NC* ncp; |
76 | 1.41M | int stat = NC_check_id(ncid,&ncp); |
77 | 1.41M | if(stat != NC_NOERR) return stat; |
78 | 1.41M | return ncp->dispatch->inq_grps(ncid,numgrps,ncids); |
79 | 1.41M | } |
80 | | |
81 | | /*! Get the name of a group given an ID. |
82 | | |
83 | | @param[in] ncid The ncid of the file or parent group. |
84 | | @param[out] name The name of the group associated with the id. |
85 | | |
86 | | @returns Error code or ::NC_NOERR for no error. |
87 | | */ |
88 | | int nc_inq_grpname(int ncid, char *name) |
89 | 2.14k | { |
90 | 2.14k | NC* ncp; |
91 | 2.14k | int stat = NC_check_id(ncid,&ncp); |
92 | 2.14k | if(stat != NC_NOERR) return stat; |
93 | 2.14k | return ncp->dispatch->inq_grpname(ncid,name); |
94 | 2.14k | } |
95 | | |
96 | | /*! Get the full path/groupname of a group/subgroup given an ID. |
97 | | |
98 | | @param[in] ncid The ncid of the file or parent group. |
99 | | @param[out] lenp Pointer to memory to hold the length of the full name. |
100 | | @param[out] full_name Pointer to memory to hold the full name of the group including root/parent. |
101 | | |
102 | | @returns Error code or ::NC_NOERR for no error. |
103 | | |
104 | | */ |
105 | | |
106 | | int nc_inq_grpname_full(int ncid, size_t *lenp, char *full_name) |
107 | 139k | { |
108 | 139k | NC* ncp; |
109 | 139k | int stat = NC_check_id(ncid,&ncp); |
110 | 139k | if(stat != NC_NOERR) return stat; |
111 | 139k | return ncp->dispatch->inq_grpname_full(ncid,lenp,full_name); |
112 | 139k | } |
113 | | |
114 | | /*! Get the length of a group name given an ID. |
115 | | |
116 | | @param[in] ncid The ncid of the group in question. |
117 | | @param[out] lenp Pointer to memory to hold the length of the name of the group in question. |
118 | | |
119 | | @returns Error code or ::NC_NOERR for no error. |
120 | | |
121 | | */ |
122 | | int nc_inq_grpname_len(int ncid, size_t *lenp) |
123 | 69.6k | { |
124 | 69.6k | int stat = nc_inq_grpname_full(ncid,lenp,NULL); |
125 | 69.6k | return stat; |
126 | 69.6k | } |
127 | | |
128 | | /*! Get the ID of the parent based on a group ID. |
129 | | |
130 | | @param[in] ncid The ncid of the group in question. |
131 | | @param[out] parent_ncid Pointer to memory to hold the identifier of the parent of the group in question. |
132 | | |
133 | | @returns Error code or ::NC_NOERR for no error. |
134 | | |
135 | | */ |
136 | | int nc_inq_grp_parent(int ncid, int *parent_ncid) |
137 | 997k | { |
138 | 997k | NC* ncp; |
139 | 997k | int stat = NC_check_id(ncid,&ncp); |
140 | 997k | if(stat != NC_NOERR) return stat; |
141 | 997k | return ncp->dispatch->inq_grp_parent(ncid,parent_ncid); |
142 | 997k | } |
143 | | |
144 | | /*! Get a group ncid given the group name. |
145 | | |
146 | | @param[in] ncid The ncid of the file. |
147 | | @param[in] grp_name The name of the group in question. |
148 | | @param[out] grp_ncid Pointer to memory to hold the identifier of the group in question. |
149 | | |
150 | | @returns Error code or ::NC_NOERR for no error. |
151 | | |
152 | | \note{This has same semantics as nc_inq_ncid} |
153 | | |
154 | | */ |
155 | | int nc_inq_grp_ncid(int ncid, const char *grp_name, int *grp_ncid) |
156 | 63 | { |
157 | 63 | return nc_inq_ncid(ncid,grp_name,grp_ncid); |
158 | 63 | } |
159 | | |
160 | | /*! Get the full ncid given a group name. |
161 | | |
162 | | @param[in] ncid The ncid of the file. |
163 | | @param[in] full_name The full name of the group in question. |
164 | | @param[out] grp_ncid Pointer to memory to hold the identifier of the full group in question. |
165 | | |
166 | | @returns Error code or ::NC_NOERR for no error. |
167 | | |
168 | | */ |
169 | | int nc_inq_grp_full_ncid(int ncid, const char *full_name, int *grp_ncid) |
170 | 4.48k | { |
171 | 4.48k | NC* ncp; |
172 | 4.48k | int stat = NC_check_id(ncid,&ncp); |
173 | 4.48k | if(stat != NC_NOERR) return stat; |
174 | 4.48k | return ncp->dispatch->inq_grp_full_ncid(ncid,full_name,grp_ncid); |
175 | 4.48k | } |
176 | | |
177 | | |
178 | | /*! Get a list of varids associated with a group given a group ID. |
179 | | |
180 | | @param[in] ncid The ncid of the group in question. |
181 | | @param[out] nvars Pointer to memory to hold the number of variables in the group in question. |
182 | | @param[out] varids Pointer to memory to hold the variable ids contained by the group in question. |
183 | | |
184 | | @returns Error code or ::NC_NOERR for no error. |
185 | | |
186 | | */ |
187 | | int nc_inq_varids(int ncid, int *nvars, int *varids) |
188 | 2.02k | { |
189 | 2.02k | NC* ncp; |
190 | 2.02k | int stat = NC_check_id(ncid,&ncp); |
191 | 2.02k | if(stat != NC_NOERR) return stat; |
192 | 2.02k | return ncp->dispatch->inq_varids(ncid,nvars,varids); |
193 | 2.02k | } |
194 | | |
195 | | /*! Retrieve a list of dimension ids associated with a group. |
196 | | |
197 | | @param[in] ncid The ncid of the group in question. |
198 | | @param[out] ndims Pointer to memory to contain the number of dimids associated with the group. |
199 | | @param[out] dimids Pointer to memory to contain the number of dimensions associated with the group. |
200 | | @param[in] include_parents If non-zero, parent groups are also traversed. |
201 | | |
202 | | @returns Error code or ::NC_NOERR for no error. |
203 | | |
204 | | */ |
205 | | int nc_inq_dimids(int ncid, int *ndims, int *dimids, int include_parents) |
206 | 1.19k | { |
207 | 1.19k | NC* ncp; |
208 | 1.19k | int stat = NC_check_id(ncid,&ncp); |
209 | 1.19k | if(stat != NC_NOERR) return stat; |
210 | 1.19k | return ncp->dispatch->inq_dimids(ncid,ndims,dimids,include_parents); |
211 | 1.19k | } |
212 | | |
213 | | /*! Retrieve a list of types associated with a group |
214 | | |
215 | | @param[in] ncid The ncid for the group in question. |
216 | | @param[out] ntypes Pointer to memory to hold the number of typeids contained by the group in question. |
217 | | @param[out] typeids Pointer to memory to hold the typeids contained by the group in question. |
218 | | |
219 | | @returns Error code or ::NC_NOERR for no error. |
220 | | |
221 | | */ |
222 | | |
223 | | int nc_inq_typeids(int ncid, int *ntypes, int *typeids) |
224 | 2.08k | { |
225 | 2.08k | NC* ncp; |
226 | 2.08k | int stat = NC_check_id(ncid,&ncp); |
227 | 2.08k | if(stat != NC_NOERR) return stat; |
228 | 2.08k | return ncp->dispatch->inq_typeids(ncid,ntypes,typeids); |
229 | 2.08k | } |
230 | | |
231 | | /*! Define a new group. |
232 | | |
233 | | The function nc_def_grp() adds a new |
234 | | group to an open netCDF dataset in define mode. It returns (as an |
235 | | argument) a group id, given the parent ncid and the name of the group. |
236 | | |
237 | | A group may be a top-level group if it is passed the ncid of the file, |
238 | | or a sub-group if passed the ncid of an existing group. |
239 | | |
240 | | @param[in] parent_ncid The ncid of the parent for the group. |
241 | | @param[in] name Name of the new group. |
242 | | @param[out] new_ncid Pointer to memory to hold the new ncid. |
243 | | |
244 | | @returns Error code or ::NC_NOERR for no error. |
245 | | |
246 | | @retval ::NC_NOERR No error. |
247 | | @retval ::NC_ENOTNC4 Not an nc4 file. |
248 | | @retval ::NC_ENOTINDEFINE Not in define mode. |
249 | | @retval ::NC_ESTRICTNC3 Not permissible in nc4 classic mode. |
250 | | @retval ::NC_EPERM Write to read only. |
251 | | @retval ::NC_ENOMEM Memory allocation (malloc) failure. |
252 | | @retval ::NC_ENAMEINUSE String match to name in use. |
253 | | |
254 | | \section nc_def_grp_example Example |
255 | | |
256 | | Here is an example using nc_def_grp() to create a new group. |
257 | | |
258 | | \code{.c} |
259 | | |
260 | | #include <netcdf.h> |
261 | | ... |
262 | | int status, ncid, grpid, latid, recid; |
263 | | ... |
264 | | |
265 | | \endcode |
266 | | |
267 | | */ |
268 | | int nc_def_grp(int parent_ncid, const char *name, int *new_ncid) |
269 | 0 | { |
270 | 0 | NC* ncp; |
271 | 0 | int stat = NC_check_id(parent_ncid,&ncp); |
272 | 0 | if(stat != NC_NOERR) return stat; |
273 | 0 | return ncp->dispatch->def_grp(parent_ncid,name,new_ncid); |
274 | 0 | } |
275 | | |
276 | | /*! Rename a group. |
277 | | |
278 | | @param[in] grpid The ID for the group in question. |
279 | | @param[in] name The new name for the group. |
280 | | |
281 | | @returns Error code or ::NC_NOERR for no error. |
282 | | |
283 | | */ |
284 | | int nc_rename_grp(int grpid, const char *name) |
285 | 0 | { |
286 | 0 | NC* ncp; |
287 | 0 | int stat = NC_check_id(grpid,&ncp); |
288 | 0 | if(stat != NC_NOERR) return stat; |
289 | 0 | return ncp->dispatch->rename_grp(grpid,name); |
290 | 0 | } |
291 | | |
292 | | /*! Print the metadata for a file. |
293 | | |
294 | | @param[in] ncid The ncid of an open file. |
295 | | |
296 | | @returns Error code or ::NC_NOERR for no error. |
297 | | |
298 | | */ |
299 | | int nc_show_metadata(int ncid) |
300 | 0 | { |
301 | 0 | NC* ncp; |
302 | 0 | int stat = NC_check_id(ncid,&ncp); |
303 | 0 | if(stat != NC_NOERR) return stat; |
304 | 0 | return ncp->dispatch->show_metadata(ncid); |
305 | 0 | } |
306 | | |
307 | | /** \} */ |