Coverage Report

Created: 2025-06-09 07:43

/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
/** \} */