1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2 * Copyright by The HDF Group. *
3 * Copyright by the Board of Trustees of the University of Illinois. *
4 * All rights reserved. *
5 * *
6 * This file is part of HDF5. The full HDF5 copyright notice, including *
7 * terms governing use, modification, and redistribution, is contained in *
8 * the COPYING file, which can be found at the root of the source code *
9 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. *
10 * If you do not have access to either file, you may request a copy from *
11 * help@hdfgroup.org. *
12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
13
14 /*-------------------------------------------------------------------------
15 *
16 * Created: H5O.c
17 *
18 * Purpose: Public object header routines
19 *
20 *-------------------------------------------------------------------------
21 */
22
23 /****************/
24 /* Module Setup */
25 /****************/
26
27 #include "H5Omodule.h" /* This source code file is part of the H5O module */
28
29
30 /***********/
31 /* Headers */
32 /***********/
33 #include "H5private.h" /* Generic Functions */
34 #include "H5CXprivate.h" /* API Contexts */
35 #include "H5Eprivate.h" /* Error handling */
36 #include "H5Fprivate.h" /* File access */
37 #include "H5Iprivate.h" /* IDs */
38 #include "H5Lprivate.h" /* Links */
39 #include "H5Opkg.h" /* Object headers */
40
41
42 /****************/
43 /* Local Macros */
44 /****************/
45
46
47 /******************/
48 /* Local Typedefs */
49 /******************/
50
51
52 /********************/
53 /* Package Typedefs */
54 /********************/
55
56
57 /********************/
58 /* Local Prototypes */
59 /********************/
60
61
62 /*********************/
63 /* Package Variables */
64 /*********************/
65
66
67 /*****************************/
68 /* Library Private Variables */
69 /*****************************/
70
71
72 /*******************/
73 /* Local Variables */
74 /*******************/
75
76
77 /*-------------------------------------------------------------------------
78 * Function: H5Oopen
79 *
80 * Purpose: Opens an object within an HDF5 file.
81 *
82 * This function opens an object in the same way that H5Gopen2,
83 * H5Topen2, and H5Dopen2 do. However, H5Oopen doesn't require
84 * the type of object to be known beforehand. This can be
85 * useful in user-defined links, for instance, when only a
86 * path is known.
87 *
88 * The opened object should be closed again with H5Oclose
89 * or H5Gclose, H5Tclose, or H5Dclose.
90 *
91 * Return: Success: An open object identifier
92 * Failure: Negative
93 *
94 * Programmer: James Laird
95 * July 14 2006
96 *
97 *-------------------------------------------------------------------------
98 */
99 hid_t
H5Oopen(hid_t loc_id,const char * name,hid_t lapl_id)100 H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id)
101 {
102 H5G_loc_t loc; /* Location of group */
103 hid_t ret_value = FAIL;
104
105 FUNC_ENTER_API(FAIL)
106 H5TRACE3("i", "i*si", loc_id, name, lapl_id);
107
108 /* Check args */
109 if(H5G_loc(loc_id, &loc) < 0)
110 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
111 if(!name || !*name)
112 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
113
114 /* Verify access property list and set up collective metadata if appropriate */
115 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, FALSE) < 0)
116 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, H5I_INVALID_HID, "can't set access property list info")
117
118 /* Open the object */
119 if((ret_value = H5O__open_name(&loc, name)) < 0)
120 HGOTO_ERROR(H5E_OHDR, H5E_CANTOPENOBJ, FAIL, "unable to open object")
121
122 done:
123 FUNC_LEAVE_API(ret_value)
124 } /* end H5Oopen() */
125
126
127 /*-------------------------------------------------------------------------
128 * Function: H5Oopen_by_idx
129 *
130 * Purpose: Opens an object within an HDF5 file, according to the offset
131 * within an index.
132 *
133 * This function opens an object in the same way that H5Gopen,
134 * H5Topen, and H5Dopen do. However, H5Oopen doesn't require
135 * the type of object to be known beforehand. This can be
136 * useful in user-defined links, for instance, when only a
137 * path is known.
138 *
139 * The opened object should be closed again with H5Oclose
140 * or H5Gclose, H5Tclose, or H5Dclose.
141 *
142 * Return: Success: An open object identifier
143 * Failure: Negative
144 *
145 * Programmer: Quincey Koziol
146 * November 20 2006
147 *
148 *-------------------------------------------------------------------------
149 */
150 hid_t
H5Oopen_by_idx(hid_t loc_id,const char * group_name,H5_index_t idx_type,H5_iter_order_t order,hsize_t n,hid_t lapl_id)151 H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
152 H5_iter_order_t order, hsize_t n, hid_t lapl_id)
153 {
154 H5G_loc_t loc; /* Location of group */
155 hid_t ret_value = FAIL;
156
157 FUNC_ENTER_API(FAIL)
158 H5TRACE6("i", "i*sIiIohi", loc_id, group_name, idx_type, order, n, lapl_id);
159
160 /* Check args */
161 if(H5G_loc(loc_id, &loc) < 0)
162 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
163 if(!group_name || !*group_name)
164 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name specified")
165 if(idx_type <= H5_INDEX_UNKNOWN || idx_type >= H5_INDEX_N)
166 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid index type specified")
167 if(order <= H5_ITER_UNKNOWN || order >= H5_ITER_N)
168 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid iteration order specified")
169
170 /* Verify access property list and set up collective metadata if appropriate */
171 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, FALSE) < 0)
172 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, H5I_INVALID_HID, "can't set access property list info")
173
174 /* Open the object */
175 if((ret_value = H5O__open_by_idx(&loc, group_name, idx_type, order, n)) < 0)
176 HGOTO_ERROR(H5E_OHDR, H5E_CANTOPENOBJ, FAIL, "unable to open object")
177
178 done:
179 FUNC_LEAVE_API(ret_value)
180 } /* end H5Oopen_by_idx() */
181
182
183 /*-------------------------------------------------------------------------
184 * Function: H5Oopen_by_addr
185 *
186 * Purpose: Warning! This function is EXTREMELY DANGEROUS!
187 * Improper use can lead to FILE CORRUPTION, INACCESSIBLE DATA,
188 * and other VERY BAD THINGS!
189 *
190 * This function opens an object using its address within the
191 * HDF5 file, similar to an HDF5 hard link. The open object
192 * is identical to an object opened with H5Oopen() and should
193 * be closed with H5Oclose() or a type-specific closing
194 * function (such as H5Gclose() ).
195 *
196 * This function is very dangerous if called on an invalid
197 * address. For this reason, H5Oincr_refcount() should be
198 * used to prevent HDF5 from deleting any object that is
199 * referenced by address (e.g. by a user-defined link).
200 * H5Odecr_refcount() should be used when the object is
201 * no longer being referenced by address (e.g. when the UD link
202 * is deleted).
203 *
204 * The address of the HDF5 file on disk has no effect on
205 * H5Oopen_by_addr(), nor does the use of any unusual file
206 * drivers. The "address" is really the offset within the
207 * HDF5 file, and HDF5's file drivers will transparently
208 * map this to an address on disk for the filesystem.
209 *
210 * Return: Success: An open object identifier
211 * Failure: Negative
212 *
213 * Programmer: James Laird
214 * July 14 2006
215 *
216 *-------------------------------------------------------------------------
217 */
218 hid_t
H5Oopen_by_addr(hid_t loc_id,haddr_t addr)219 H5Oopen_by_addr(hid_t loc_id, haddr_t addr)
220 {
221 H5G_loc_t loc; /* Location within file */
222 hid_t ret_value = H5I_INVALID_HID; /* Return value */
223
224 FUNC_ENTER_API(FAIL)
225 H5TRACE2("i", "ia", loc_id, addr);
226
227 /* Check args */
228 if(H5G_loc(loc_id, &loc) < 0)
229 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a location")
230 if(!H5F_addr_defined(addr))
231 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, H5I_INVALID_HID, "no address supplied")
232
233 /* Open the object */
234 if((ret_value = H5O__open_by_addr(&loc, addr)) < 0)
235 HGOTO_ERROR(H5E_OHDR, H5E_CANTOPENOBJ, FAIL, "unable to open object")
236
237 done:
238 FUNC_LEAVE_API(ret_value)
239 } /* end H5Oopen_by_addr() */
240
241
242 /*-------------------------------------------------------------------------
243 * Function: H5Olink
244 *
245 * Purpose: Creates a hard link from NEW_NAME to the object specified
246 * by OBJ_ID using properties defined in the Link Creation
247 * Property List LCPL.
248 *
249 * This function should be used to link objects that have just
250 * been created.
251 *
252 * NEW_NAME is interpreted relative to
253 * NEW_LOC_ID, which is either a file ID or a
254 * group ID.
255 *
256 * Return: Non-negative on success/Negative on failure
257 *
258 * Programmer: James Laird
259 * Tuesday, December 13, 2005
260 *
261 *-------------------------------------------------------------------------
262 */
263 herr_t
H5Olink(hid_t obj_id,hid_t new_loc_id,const char * new_name,hid_t lcpl_id,hid_t lapl_id)264 H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_t lcpl_id,
265 hid_t lapl_id)
266 {
267 H5G_loc_t new_loc; /* Location of group to link from */
268 H5G_loc_t obj_loc; /* Location of object to link to */
269 herr_t ret_value = SUCCEED; /* Return value */
270
271 FUNC_ENTER_API(FAIL)
272 H5TRACE5("e", "ii*sii", obj_id, new_loc_id, new_name, lcpl_id, lapl_id);
273
274 /* Check arguments */
275 if(H5G_loc(obj_id, &obj_loc) < 0)
276 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
277 if(new_loc_id == H5L_SAME_LOC)
278 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "cannot use H5L_SAME_LOC when only one location is specified")
279 if(H5G_loc(new_loc_id, &new_loc) < 0)
280 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
281 if(!new_name || !*new_name)
282 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name specified")
283 /* Avoid compiler warning on 32-bit machines */
284 #if H5_SIZEOF_SIZE_T > H5_SIZEOF_INT32_T
285 if(HDstrlen(new_name) > H5L_MAX_LINK_NAME_LEN)
286 HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "name too long")
287 #endif /* H5_SIZEOF_SIZE_T > H5_SIZEOF_INT32_T */
288 if(lcpl_id != H5P_DEFAULT && (TRUE != H5P_isa_class(lcpl_id, H5P_LINK_CREATE)))
289 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a link creation property list")
290
291 /* Verify access property list and set up collective metadata if appropriate */
292 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, obj_id, TRUE) < 0)
293 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
294
295 /* Create a link to the object */
296 if(H5O__create_link(&new_loc, new_name, &obj_loc, lcpl_id) < 0)
297 HGOTO_ERROR(H5E_OHDR, H5E_CANTINIT, FAIL, "unable to create link")
298
299 done:
300 FUNC_LEAVE_API(ret_value)
301 } /* end H5Olink() */
302
303
304 /*-------------------------------------------------------------------------
305 * Function: H5Oincr_refcount
306 *
307 * Purpose: Warning! This function is EXTREMELY DANGEROUS!
308 * Improper use can lead to FILE CORRUPTION, INACCESSIBLE DATA,
309 * and other VERY BAD THINGS!
310 *
311 * This function increments the "hard link" reference count
312 * for an object. It should be used when a user-defined link
313 * that references an object by address is created. When the
314 * link is deleted, H5Odecr_refcount should be used.
315 *
316 * Return: Success: Non-negative
317 * Failure: Negative
318 *
319 * Programmer: James Laird
320 * July 14 2006
321 *
322 *-------------------------------------------------------------------------
323 */
324 herr_t
H5Oincr_refcount(hid_t object_id)325 H5Oincr_refcount(hid_t object_id)
326 {
327 H5O_loc_t *oloc; /* Object location */
328 herr_t ret_value = SUCCEED; /* Return value */
329
330 FUNC_ENTER_API(FAIL)
331 H5TRACE1("e", "i", object_id);
332
333 /* Get the object's oloc so we can adjust its link count */
334 if((oloc = H5O_get_loc(object_id)) == NULL)
335 HGOTO_ERROR(H5E_ATOM, H5E_BADVALUE, FAIL, "unable to get object location from ID")
336
337 /* Set up collective metadata if appropriate */
338 if(H5CX_set_loc(object_id) < 0)
339 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
340
341 /* Change the object's refcount */
342 if(H5O__link(oloc, 1) < 0)
343 HGOTO_ERROR(H5E_OHDR, H5E_LINKCOUNT, FAIL, "modifying object link count failed")
344
345 done:
346 FUNC_LEAVE_API(ret_value)
347 } /* end H5O_incr_refcount() */
348
349
350 /*-------------------------------------------------------------------------
351 * Function: H5Odecr_refcount
352 *
353 * Purpose: Warning! This function is EXTREMELY DANGEROUS!
354 * Improper use can lead to FILE CORRUPTION, INACCESSIBLE DATA,
355 * and other VERY BAD THINGS!
356 *
357 * This function decrements the "hard link" reference count
358 * for an object. It should be used when user-defined links
359 * that reference an object by address are deleted, and only
360 * after H5Oincr_refcount has already been used.
361 *
362 * Return: Success: Non-negative
363 * Failure: Negative
364 *
365 * Programmer: James Laird
366 * July 14 2006
367 *
368 *-------------------------------------------------------------------------
369 */
370 herr_t
H5Odecr_refcount(hid_t object_id)371 H5Odecr_refcount(hid_t object_id)
372 {
373 H5O_loc_t *oloc; /* Object location */
374 herr_t ret_value = SUCCEED; /* Return value */
375
376 FUNC_ENTER_API(FAIL)
377 H5TRACE1("e", "i", object_id);
378
379 /* Get the object's oloc so we can adjust its link count */
380 if((oloc = H5O_get_loc(object_id)) == NULL)
381 HGOTO_ERROR(H5E_ATOM, H5E_BADVALUE, FAIL, "unable to get object location from ID")
382
383 /* Set up collective metadata if appropriate */
384 if(H5CX_set_loc(object_id) < 0)
385 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
386
387 /* Change the object's refcount */
388 if(H5O__link(oloc, -1) < 0)
389 HGOTO_ERROR(H5E_OHDR, H5E_LINKCOUNT, FAIL, "modifying object link count failed")
390
391 done:
392 FUNC_LEAVE_API(ret_value)
393 } /* end H5Odecr_refcount() */
394
395
396 /*-------------------------------------------------------------------------
397 * Function: H5Oexists_by_name
398 *
399 * Purpose: Determine if a linked-to object exists
400 *
401 * Return: Success: TRUE/FALSE
402 * Failure: Negative
403 *
404 * Programmer: Quincey Koziol
405 * February 2 2010
406 *
407 *-------------------------------------------------------------------------
408 */
409 htri_t
H5Oexists_by_name(hid_t loc_id,const char * name,hid_t lapl_id)410 H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id)
411 {
412 H5G_loc_t loc; /* Location info */
413 htri_t ret_value = FAIL; /* Return value */
414
415 FUNC_ENTER_API(FAIL)
416 H5TRACE3("t", "i*si", loc_id, name, lapl_id);
417
418 /* Check args */
419 if(H5G_loc(loc_id, &loc) < 0)
420 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
421 if(!name || !*name)
422 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
423
424 /* Verify access property list and set up collective metadata if appropriate */
425 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, FALSE) < 0)
426 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
427
428 /* Check if the object exists */
429 if((ret_value = H5O__exists_by_name(&loc, name)) < 0)
430 HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, FAIL, "unable to determine if '%s' exists", name)
431
432 done:
433 FUNC_LEAVE_API(ret_value)
434 } /* end H5Oexists_by_name() */
435
436
437 /*-------------------------------------------------------------------------
438 * Function: H5Oget_info2
439 *
440 * Purpose: Retrieve information about an object.
441 *
442 * NOTE: Add a parameter "fields" to indicate selection of object info.
443 *
444 * Return: Success: Non-negative
445 * Failure: Negative
446 *
447 * Programmer: Neil Fortner
448 * July 7 2010
449 *
450 *-------------------------------------------------------------------------
451 */
452 herr_t
H5Oget_info2(hid_t loc_id,H5O_info_t * oinfo,unsigned fields)453 H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields)
454 {
455 H5G_loc_t loc; /* Location of group */
456 herr_t ret_value = SUCCEED; /* Return value */
457
458 FUNC_ENTER_API(FAIL)
459 H5TRACE3("e", "i*xIu", loc_id, oinfo, fields);
460
461 /* Check args */
462 if(H5G_loc(loc_id, &loc) < 0)
463 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
464 if(!oinfo)
465 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no info struct")
466 if(fields & ~H5O_INFO_ALL)
467 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid fields")
468
469 /* Retrieve the object's information */
470 if(H5O__get_info_by_name(&loc, ".", oinfo/*out*/, fields) < 0)
471 HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, FAIL, "can't get info for object")
472
473 done:
474 FUNC_LEAVE_API(ret_value)
475 } /* end H5Oget_info2() */
476
477
478 /*-------------------------------------------------------------------------
479 * Function: H5Oget_info_by_name2
480 *
481 * Purpose: Retrieve information about an object.
482 *
483 * NOTE: Add a parameter "fields" to indicate selection of object info.
484 *
485 * Return: Success: Non-negative
486 * Failure: Negative
487 *
488 * Programmer: Neil Fortner
489 * July 7 2010
490 *
491 *-------------------------------------------------------------------------
492 */
493 herr_t
H5Oget_info_by_name2(hid_t loc_id,const char * name,H5O_info_t * oinfo,unsigned fields,hid_t lapl_id)494 H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *oinfo,
495 unsigned fields, hid_t lapl_id)
496 {
497 H5G_loc_t loc; /* Location of group */
498 herr_t ret_value = SUCCEED; /* Return value */
499
500 FUNC_ENTER_API(FAIL)
501 H5TRACE5("e", "i*s*xIui", loc_id, name, oinfo, fields, lapl_id);
502
503 /* Check args */
504 if(H5G_loc(loc_id, &loc) < 0)
505 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
506 if(!name || !*name)
507 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
508 if(!oinfo)
509 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no info struct")
510 if(fields & ~H5O_INFO_ALL)
511 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid fields")
512
513 /* Verify access property list and set up collective metadata if appropriate */
514 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, FALSE) < 0)
515 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
516
517 /* Retrieve the object's information */
518 if(H5O__get_info_by_name(&loc, name, oinfo/*out*/, fields) < 0)
519 HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, FAIL, "can't get info for object: '%s'", name)
520
521 done:
522 FUNC_LEAVE_API(ret_value)
523 } /* end H5Oget_info_by_name2() */
524
525
526 /*-------------------------------------------------------------------------
527 * Function: H5Oget_info_by_idx2
528 *
529 * Purpose: Retrieve information about an object, according to the order
530 * of an index.
531 *
532 * NOTE: Add a parameter "fields" to indicate selection of object info.
533 *
534 * Return: Success: Non-negative
535 * Failure: Negative
536 *
537 * Programmer: Quincey Koziol
538 * November 26 2006
539 *
540 *-------------------------------------------------------------------------
541 */
542 herr_t
H5Oget_info_by_idx2(hid_t loc_id,const char * group_name,H5_index_t idx_type,H5_iter_order_t order,hsize_t n,H5O_info_t * oinfo,unsigned fields,hid_t lapl_id)543 H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
544 H5_iter_order_t order, hsize_t n, H5O_info_t *oinfo, unsigned fields, hid_t lapl_id)
545 {
546 H5G_loc_t loc; /* Location of group */
547 herr_t ret_value = SUCCEED; /* Return value */
548
549 FUNC_ENTER_API(FAIL)
550 H5TRACE8("e", "i*sIiIoh*xIui", loc_id, group_name, idx_type, order, n, oinfo,
551 fields, lapl_id);
552
553 /* Check args */
554 if(H5G_loc(loc_id, &loc) < 0)
555 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
556 if(!group_name || !*group_name)
557 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name specified")
558 if(idx_type <= H5_INDEX_UNKNOWN || idx_type >= H5_INDEX_N)
559 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid index type specified")
560 if(order <= H5_ITER_UNKNOWN || order >= H5_ITER_N)
561 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid iteration order specified")
562 if(!oinfo)
563 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no info struct")
564 if(fields & ~H5O_INFO_ALL)
565 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid fields")
566
567 /* Verify access property list and set up collective metadata if appropriate */
568 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, FALSE) < 0)
569 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
570
571 /* Retrieve the object's information */
572 if(H5O__get_info_by_idx(&loc, group_name, idx_type, order, n, oinfo, fields) < 0)
573 HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, FAIL, "can't get info for object")
574
575 done:
576 FUNC_LEAVE_API(ret_value)
577 } /* end H5Oget_info_by_idx2() */
578
579
580 /*-------------------------------------------------------------------------
581 * Function: H5Oset_comment
582 *
583 * Purpose: Gives the specified object a comment. The COMMENT string
584 * should be a null terminated string. An object can have only
585 * one comment at a time. Passing NULL for the COMMENT argument
586 * will remove the comment property from the object.
587 *
588 * Note: Deprecated in favor of using attributes on objects
589 *
590 * Return: Non-negative on success/Negative on failure
591 *
592 * Programmer: Quincey Koziol
593 * August 30 2007
594 *
595 *-------------------------------------------------------------------------
596 */
597 herr_t
H5Oset_comment(hid_t obj_id,const char * comment)598 H5Oset_comment(hid_t obj_id, const char *comment)
599 {
600 H5G_loc_t loc; /* Location of group */
601 herr_t ret_value = SUCCEED; /* Return value */
602
603 FUNC_ENTER_API(FAIL)
604 H5TRACE2("e", "i*s", obj_id, comment);
605
606 /* Check args */
607 if(H5G_loc(obj_id, &loc) < 0)
608 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
609
610 /* Set up collective metadata if appropriate */
611 if(H5CX_set_loc(obj_id) < 0)
612 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set collective metadata read info")
613
614 /* (Re)set the object's comment */
615 if(H5O__set_comment_by_name(&loc, ".", comment) < 0)
616 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set comment for object")
617
618 done:
619 FUNC_LEAVE_API(ret_value)
620 } /* end H5Oset_comment() */
621
622
623 /*-------------------------------------------------------------------------
624 * Function: H5Oset_comment_by_name
625 *
626 * Purpose: Gives the specified object a comment. The COMMENT string
627 * should be a null terminated string. An object can have only
628 * one comment at a time. Passing NULL for the COMMENT argument
629 * will remove the comment property from the object.
630 *
631 * Note: Deprecated in favor of using attributes on objects
632 *
633 * Return: Non-negative on success/Negative on failure
634 *
635 * Programmer: Quincey Koziol
636 * August 30 2007
637 *
638 *-------------------------------------------------------------------------
639 */
640 herr_t
H5Oset_comment_by_name(hid_t loc_id,const char * name,const char * comment,hid_t lapl_id)641 H5Oset_comment_by_name(hid_t loc_id, const char *name, const char *comment,
642 hid_t lapl_id)
643 {
644 H5G_loc_t loc; /* Location of group */
645 herr_t ret_value = SUCCEED; /* Return value */
646
647 FUNC_ENTER_API(FAIL)
648 H5TRACE4("e", "i*s*si", loc_id, name, comment, lapl_id);
649
650 /* Check args */
651 if(H5G_loc(loc_id, &loc) < 0)
652 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
653 if(!name || !*name)
654 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
655
656 /* Verify access property list and set up collective metadata if appropriate */
657 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, TRUE) < 0)
658 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
659
660 /* (Re)set the object's comment */
661 if(H5O__set_comment_by_name(&loc, name, comment) < 0)
662 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set comment for object: '%s'", name)
663
664 done:
665 FUNC_LEAVE_API(ret_value)
666 } /* end H5Oset_comment_by_name() */
667
668
669 /*-------------------------------------------------------------------------
670 * Function: H5Oget_comment
671 *
672 * Purpose: Retrieve comment for an object.
673 *
674 * Return: Success: Number of bytes in the comment excluding the
675 * null terminator. Zero if the object has no
676 * comment.
677 *
678 * Failure: Negative
679 *
680 * Programmer: Quincey Koziol
681 * August 30 2007
682 *
683 *-------------------------------------------------------------------------
684 */
685 ssize_t
H5Oget_comment(hid_t obj_id,char * comment,size_t bufsize)686 H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize)
687 {
688 H5G_loc_t loc; /* Location of group */
689 ssize_t ret_value; /* Return value */
690
691 FUNC_ENTER_API(FAIL)
692 H5TRACE3("Zs", "i*sz", obj_id, comment, bufsize);
693
694 /* Check args */
695 if(H5G_loc(obj_id, &loc) < 0)
696 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
697
698 /* Retrieve the object's comment */
699 if((ret_value = H5O__get_comment_by_name(&loc, ".", comment/*out*/, bufsize)) < 0)
700 HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, FAIL, "can't get comment for object")
701
702 done:
703 FUNC_LEAVE_API(ret_value)
704 } /* end H5Oget_comment() */
705
706
707 /*-------------------------------------------------------------------------
708 * Function: H5Oget_comment_by_name
709 *
710 * Purpose: Retrieve comment for an object.
711 *
712 * Return: Success: Number of bytes in the comment excluding the
713 * null terminator. Zero if the object has no
714 * comment.
715 *
716 * Failure: Negative
717 *
718 * Programmer: Quincey Koziol
719 * August 30 2007
720 *
721 *-------------------------------------------------------------------------
722 */
723 ssize_t
H5Oget_comment_by_name(hid_t loc_id,const char * name,char * comment,size_t bufsize,hid_t lapl_id)724 H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comment, size_t bufsize,
725 hid_t lapl_id)
726 {
727 H5G_loc_t loc; /* Location of group */
728 ssize_t ret_value; /* Return value */
729
730 FUNC_ENTER_API(FAIL)
731 H5TRACE5("Zs", "i*s*szi", loc_id, name, comment, bufsize, lapl_id);
732
733 /* Check args */
734 if(H5G_loc(loc_id, &loc) < 0)
735 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
736 if(!name || !*name)
737 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
738
739 /* Verify access property list and set up collective metadata if appropriate */
740 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, FALSE) < 0)
741 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
742
743 /* Retrieve the object's comment */
744 if((ret_value = H5O__get_comment_by_name(&loc, name, comment/*out*/, bufsize)) < 0)
745 HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, FAIL, "can't get comment for object: '%s'", name)
746
747 done:
748 FUNC_LEAVE_API(ret_value)
749 } /* end H5Oget_comment_by_name() */
750
751
752 /*-------------------------------------------------------------------------
753 * Function: H5Ovisit2
754 *
755 * Purpose: Recursively visit an object and all the objects reachable
756 * from it. If the starting object is a group, all the objects
757 * linked to from that group will be visited. Links within
758 * each group are visited according to the order within the
759 * specified index (unless the specified index does not exist for
760 * a particular group, then the "name" index is used).
761 *
762 * NOTE: Soft links and user-defined links are ignored during
763 * this operation.
764 *
765 * NOTE: Each _object_ reachable from the initial group will only
766 * be visited once. If multiple hard links point to the same
767 * object, the first link to the object's path (according to the
768 * iteration index and iteration order given) will be used to in
769 * the callback about the object.
770 *
771 * NOTE: Add a a parameter "fields" to indicate selection of
772 * object info to be retrieved to the callback "op".
773 *
774 * Return: Success: The return value of the first operator that
775 * returns non-zero, or zero if all members were
776 * processed with no operator returning non-zero.
777 *
778 * Failure: Negative if something goes wrong within the
779 * library, or the negative value returned by one
780 * of the operators.
781 *
782 * Programmer: Quincey Koziol
783 * November 25 2007
784 *
785 *-------------------------------------------------------------------------
786 */
787 herr_t
H5Ovisit2(hid_t obj_id,H5_index_t idx_type,H5_iter_order_t order,H5O_iterate_t op,void * op_data,unsigned fields)788 H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order,
789 H5O_iterate_t op, void *op_data, unsigned fields)
790 {
791 herr_t ret_value; /* Return value */
792
793 FUNC_ENTER_API(FAIL)
794 H5TRACE6("e", "iIiIox*xIu", obj_id, idx_type, order, op, op_data, fields);
795
796 /* Check args */
797 if(idx_type <= H5_INDEX_UNKNOWN || idx_type >= H5_INDEX_N)
798 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid index type specified")
799 if(order <= H5_ITER_UNKNOWN || order >= H5_ITER_N)
800 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid iteration order specified")
801 if(!op)
802 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no callback operator specified")
803 if(fields & ~H5O_INFO_ALL)
804 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid fields")
805
806 /* Call internal object visitation routine */
807 if((ret_value = H5O__visit(obj_id, ".", idx_type, order, op, op_data, fields)) < 0)
808 HGOTO_ERROR(H5E_OHDR, H5E_BADITER, FAIL, "object visitation failed")
809
810 done:
811 FUNC_LEAVE_API(ret_value)
812 } /* end H5Ovisit2() */
813
814
815 /*-------------------------------------------------------------------------
816 * Function: H5Ovisit_by_name2
817 *
818 * Purpose: Recursively visit an object and all the objects reachable
819 * from it. If the starting object is a group, all the objects
820 * linked to from that group will be visited. Links within
821 * each group are visited according to the order within the
822 * specified index (unless the specified index does not exist for
823 * a particular group, then the "name" index is used).
824 *
825 * NOTE: Soft links and user-defined links are ignored during
826 * this operation.
827 *
828 * NOTE: Each _object_ reachable from the initial group will only
829 * be visited once. If multiple hard links point to the same
830 * object, the first link to the object's path (according to the
831 * iteration index and iteration order given) will be used to in
832 * the callback about the object.
833 *
834 * NOTE: Add a a parameter "fields" to indicate selection of
835 * object info to be retrieved to the callback "op".
836 *
837 * Return: Success: The return value of the first operator that
838 * returns non-zero, or zero if all members were
839 * processed with no operator returning non-zero.
840 *
841 * Failure: Negative if something goes wrong within the
842 * library, or the negative value returned by one
843 * of the operators.
844 *
845 * Programmer: Quincey Koziol
846 * November 24 2007
847 *
848 *-------------------------------------------------------------------------
849 */
850 herr_t
H5Ovisit_by_name2(hid_t loc_id,const char * obj_name,H5_index_t idx_type,H5_iter_order_t order,H5O_iterate_t op,void * op_data,unsigned fields,hid_t lapl_id)851 H5Ovisit_by_name2(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
852 H5_iter_order_t order, H5O_iterate_t op, void *op_data, unsigned fields, hid_t lapl_id)
853 {
854 herr_t ret_value; /* Return value */
855
856 FUNC_ENTER_API(FAIL)
857 H5TRACE8("e", "i*sIiIox*xIui", loc_id, obj_name, idx_type, order, op, op_data,
858 fields, lapl_id);
859
860 /* Check args */
861 if(!obj_name || !*obj_name)
862 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
863 if(idx_type <= H5_INDEX_UNKNOWN || idx_type >= H5_INDEX_N)
864 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid index type specified")
865 if(order <= H5_ITER_UNKNOWN || order >= H5_ITER_N)
866 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid iteration order specified")
867 if(!op)
868 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no callback operator specified")
869 if(fields & ~H5O_INFO_ALL)
870 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid fields")
871
872 /* Verify access property list and set up collective metadata if appropriate */
873 if(H5CX_set_apl(&lapl_id, H5P_CLS_LACC, loc_id, FALSE) < 0)
874 HGOTO_ERROR(H5E_OHDR, H5E_CANTSET, FAIL, "can't set access property list info")
875
876 /* Call internal object visitation routine */
877 if((ret_value = H5O__visit(loc_id, obj_name, idx_type, order, op, op_data, fields)) < 0)
878 HGOTO_ERROR(H5E_OHDR, H5E_BADITER, FAIL, "object visitation failed")
879
880 done:
881 FUNC_LEAVE_API(ret_value)
882 } /* end H5Ovisit_by_name2() */
883
884
885 /*-------------------------------------------------------------------------
886 * Function: H5Oclose
887 *
888 * Purpose: Close an open file object.
889 *
890 * This is the companion to H5Oopen. It is used to close any
891 * open object in an HDF5 file (but not IDs are that not file
892 * objects, such as property lists and dataspaces). It has
893 * the same effect as calling H5Gclose, H5Dclose, or H5Tclose.
894 *
895 * Return: Success: Non-negative
896 * Failure: Negative
897 *
898 * Programmer: James Laird
899 * July 14 2006
900 *
901 *-------------------------------------------------------------------------
902 */
903 herr_t
H5Oclose(hid_t object_id)904 H5Oclose(hid_t object_id)
905 {
906 herr_t ret_value = SUCCEED;
907
908 FUNC_ENTER_API(FAIL)
909 H5TRACE1("e", "i", object_id);
910
911 /* Get the type of the object and close it in the correct way */
912 switch(H5I_get_type(object_id)) {
913 case H5I_GROUP:
914 case H5I_DATATYPE:
915 case H5I_DATASET:
916 if(H5I_object(object_id) == NULL)
917 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a valid object")
918 if(H5I_dec_app_ref(object_id) < 0)
919 HGOTO_ERROR(H5E_OHDR, H5E_CANTRELEASE, FAIL, "unable to close object")
920 break;
921
922 case H5I_UNINIT:
923 case H5I_BADID:
924 case H5I_FILE:
925 case H5I_DATASPACE:
926 case H5I_ATTR:
927 case H5I_REFERENCE:
928 case H5I_VFL:
929 case H5I_GENPROP_CLS:
930 case H5I_GENPROP_LST:
931 case H5I_ERROR_CLASS:
932 case H5I_ERROR_MSG:
933 case H5I_ERROR_STACK:
934 case H5I_NTYPES:
935 default:
936 HGOTO_ERROR(H5E_ARGS, H5E_CANTRELEASE, FAIL, "not a valid file object ID (dataset, group, or datatype)")
937 break;
938 } /* end switch */
939
940 done:
941 FUNC_LEAVE_API(ret_value)
942 } /* end H5Oclose() */
943
944
945 /*-------------------------------------------------------------------------
946 * Function: H5Odisable_mdc_flushes
947 *
948 * Purpose: To "cork" an object:
949 * --keep dirty entries associated with the object in the metadata cache
950 *
951 * Return: Success: Non-negative
952 * Failure: Negative
953 *
954 * Programmer: Vailin Choi
955 * January 2014
956 *
957 *-------------------------------------------------------------------------
958 */
959 herr_t
H5Odisable_mdc_flushes(hid_t object_id)960 H5Odisable_mdc_flushes(hid_t object_id)
961 {
962 H5O_loc_t *oloc; /* Object location */
963 herr_t ret_value = SUCCEED; /* Return value */
964
965 FUNC_ENTER_API(FAIL)
966 H5TRACE1("e", "i", object_id);
967
968 /* Get the object's oloc */
969 if(NULL == (oloc = H5O_get_loc(object_id)))
970 HGOTO_ERROR(H5E_OHDR, H5E_BADVALUE, FAIL, "unable to get object location from ID")
971
972 if(H5AC_cork(oloc->file, oloc->addr, H5AC__SET_CORK, NULL) < 0)
973 HGOTO_ERROR(H5E_OHDR, H5E_CANTCORK, FAIL, "unable to cork an object")
974
975 done:
976 FUNC_LEAVE_API(ret_value)
977 } /* H5Odisable_mdc_flushes() */
978
979
980 /*-------------------------------------------------------------------------
981 * Function: H5Oenable_mdc_flushes
982 *
983 * Purpose: To "uncork" an object
984 * --release keeping dirty entries associated with the object
985 * in the metadata cache
986 *
987 * Return: Success: Non-negative
988 * Failure: Negative
989 *
990 * Programmer: Vailin Choi
991 * January 2014
992 *
993 *-------------------------------------------------------------------------
994 */
995 herr_t
H5Oenable_mdc_flushes(hid_t object_id)996 H5Oenable_mdc_flushes(hid_t object_id)
997 {
998 H5O_loc_t *oloc; /* Object location */
999 herr_t ret_value = SUCCEED; /* Return value */
1000
1001 FUNC_ENTER_API(FAIL)
1002 H5TRACE1("e", "i", object_id);
1003
1004 /* Get the object's oloc */
1005 if(NULL == (oloc = H5O_get_loc(object_id)))
1006 HGOTO_ERROR(H5E_OHDR, H5E_BADVALUE, FAIL, "unable to get object location from ID")
1007
1008 /* Set the value */
1009 if(H5AC_cork(oloc->file, oloc->addr, H5AC__UNCORK, NULL) < 0)
1010 HGOTO_ERROR(H5E_OHDR, H5E_CANTUNCORK, FAIL, "unable to uncork an object")
1011
1012 done:
1013 FUNC_LEAVE_API(ret_value)
1014 } /* H5Oenable_mdc_flushes() */
1015
1016
1017 /*-------------------------------------------------------------------------
1018 * Function: H5Oare_mdc_flushes_disabled
1019 *
1020 * Purpose: Retrieve the object's "cork" status in the parameter "are_disabled":
1021 * TRUE if mdc flushes for the object is disabled
1022 * FALSE if mdc flushes for the object is not disabled
1023 * Return error if the parameter "are_disabled" is not supplied
1024 *
1025 * Return: Success: Non-negative
1026 * Failure: Negative
1027 *
1028 * Programmer: Vailin Choi
1029 * January 2014
1030 *
1031 *-------------------------------------------------------------------------
1032 */
1033 herr_t
H5Oare_mdc_flushes_disabled(hid_t object_id,hbool_t * are_disabled)1034 H5Oare_mdc_flushes_disabled(hid_t object_id, hbool_t *are_disabled)
1035 {
1036 H5O_loc_t *oloc; /* Object location */
1037 herr_t ret_value = SUCCEED; /* Return value */
1038
1039 FUNC_ENTER_API(FAIL)
1040 H5TRACE2("e", "i*b", object_id, are_disabled);
1041
1042 /* Check args */
1043
1044 /* Get the object's oloc */
1045 if(NULL == (oloc = H5O_get_loc(object_id)))
1046 HGOTO_ERROR(H5E_OHDR, H5E_BADVALUE, FAIL, "unable to get object location from ID")
1047 if(!are_disabled)
1048 HGOTO_ERROR(H5E_OHDR, H5E_BADVALUE, FAIL, "unable to get object location from ID")
1049
1050 /* Get the cork status */
1051 if(H5AC_cork(oloc->file, oloc->addr, H5AC__GET_CORKED, are_disabled) < 0)
1052 HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, FAIL, "unable to retrieve an object's cork status")
1053
1054 done:
1055 FUNC_LEAVE_API(ret_value)
1056 } /* H5Oare_mdc_flushes_disabled() */
1057
1058