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 /* Module Setup */
16 /****************/
17
18 #define H5F_PACKAGE /*suppress error about including H5Fpkg */
19
20 /* Interface initialization */
21 #define H5_INTERFACE_INIT_FUNC H5F__init_pub_interface
22
23
24 /***********/
25 /* Headers */
26 /***********/
27 #include "H5private.h" /* Generic Functions */
28 #include "H5Aprivate.h" /* Attributes */
29 #include "H5ACprivate.h" /* Metadata cache */
30 #include "H5Dprivate.h" /* Datasets */
31 #include "H5Eprivate.h" /* Error handling */
32 #include "H5Fpkg.h" /* File access */
33 #include "H5FDprivate.h" /* File drivers */
34 #include "H5Gprivate.h" /* Groups */
35 #include "H5Iprivate.h" /* IDs */
36 #include "H5MFprivate.h" /* File memory management */
37 #include "H5MMprivate.h" /* Memory management */
38 #include "H5Pprivate.h" /* Property lists */
39 #include "H5SMprivate.h" /* Shared Object Header Messages */
40 #include "H5Tprivate.h" /* Datatypes */
41
42
43 /****************/
44 /* Local Macros */
45 /****************/
46
47
48 /******************/
49 /* Local Typedefs */
50 /******************/
51
52
53 /********************/
54 /* Package Typedefs */
55 /********************/
56
57
58 /********************/
59 /* Local Prototypes */
60 /********************/
61
62
63
64 /*********************/
65 /* Package Variables */
66 /*********************/
67
68
69 /*****************************/
70 /* Library Private Variables */
71 /*****************************/
72
73
74 /*******************/
75 /* Local Variables */
76 /*******************/
77
78
79 /* File ID class */
80 static const H5I_class_t H5I_FILE_CLS[1] = {{
81 H5I_FILE, /* ID class value */
82 H5I_CLASS_REUSE_IDS, /* Class flags */
83 0, /* # of reserved IDs for class */
84 (H5I_free_t)H5F_close /* Callback routine for closing objects of this class */
85 }};
86
87
88 /*--------------------------------------------------------------------------
89 NAME
90 H5F__init_pub_interface -- Initialize interface-specific information
91 USAGE
92 herr_t H5F__init_pub_interface()
93 RETURNS
94 Non-negative on success/Negative on failure
95 DESCRIPTION
96 Initializes any interface-specific data or routines. (Just calls
97 H5F_init() currently).
98
99 --------------------------------------------------------------------------*/
100 static herr_t
H5F__init_pub_interface(void)101 H5F__init_pub_interface(void)
102 {
103 herr_t ret_value = SUCCEED; /* Return value */
104 FUNC_ENTER_STATIC
105
106 /*
107 * Initialize the atom group for the file IDs.
108 */
109 if(H5I_register_type(H5I_FILE_CLS) < 0)
110 HGOTO_ERROR(H5E_FILE, H5E_CANTINIT, FAIL, "unable to initialize interface")
111
112 ret_value = H5F_init();
113 done:
114 FUNC_LEAVE_NOAPI(ret_value)
115 } /* H5F__init_pub_interface() */
116
117
118 /*-------------------------------------------------------------------------
119 * Function: H5F_init
120 *
121 * Purpose: Initialize the interface from some other layer.
122 *
123 * Return: Success: non-negative
124 * Failure: negative
125 *
126 * Programmer: Robb Matzke
127 * Wednesday, December 16, 1998
128 *
129 *-------------------------------------------------------------------------
130 */
131 herr_t
H5F_init(void)132 H5F_init(void)
133 {
134 herr_t ret_value = SUCCEED; /* Return value */
135
136 FUNC_ENTER_NOAPI(FAIL)
137 /* FUNC_ENTER() does all the work */
138
139 done:
140 FUNC_LEAVE_NOAPI(ret_value)
141 } /* end H5F_init() */
142
143
144 /*-------------------------------------------------------------------------
145 * Function: H5F_term_interface
146 *
147 * Purpose: Terminate this interface: free all memory and reset global
148 * variables to their initial values. Release all ID groups
149 * associated with this interface.
150 *
151 * Return: Success: Positive if anything was done that might
152 * have affected other interfaces; zero
153 * otherwise.
154 *
155 * Failure: Never fails.
156 *
157 * Programmer: Robb Matzke
158 * Friday, February 19, 1999
159 *
160 *-------------------------------------------------------------------------
161 */
162 int
H5F_term_interface(void)163 H5F_term_interface(void)
164 {
165 int n = 0;
166
167 FUNC_ENTER_NOAPI_NOINIT_NOERR
168
169 if(H5_interface_initialize_g) {
170 if(H5I_nmembers(H5I_FILE) > 0) {
171 (void)H5I_clear_type(H5I_FILE, FALSE, FALSE);
172 n++; /*H5I*/
173 } /* end if */
174 else {
175 /* Make certain we've cleaned up all the shared file objects */
176 H5F_sfile_assert_num(0);
177
178 /* Destroy the file object id group */
179 (void)H5I_dec_type_ref(H5I_FILE);
180 n++; /*H5I*/
181
182 /* Mark closed */
183 H5_interface_initialize_g = 0;
184 } /* end else */
185 } /* end if */
186
187 FUNC_LEAVE_NOAPI(n)
188 } /* end H5F_term_interface() */
189
190
191 /*-------------------------------------------------------------------------
192 * Function: H5Fget_create_plist
193 *
194 * Purpose: Get an atom for a copy of the file-creation property list for
195 * this file. This function returns an atom with a copy of the
196 * properties used to create a file.
197 *
198 * Return: Success: template ID
199 *
200 * Failure: FAIL
201 *
202 * Programmer: Unknown
203 *
204 *-------------------------------------------------------------------------
205 */
206 hid_t
H5Fget_create_plist(hid_t file_id)207 H5Fget_create_plist(hid_t file_id)
208 {
209 H5F_t *file; /* File info */
210 H5P_genplist_t *plist; /* Property list */
211 hid_t ret_value; /* Return value */
212
213 FUNC_ENTER_API(FAIL)
214 H5TRACE1("i", "i", file_id);
215
216 /* check args */
217 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
218 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file")
219 if(NULL == (plist = (H5P_genplist_t *)H5I_object(file->shared->fcpl_id)))
220 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a property list")
221
222 /* Create the property list object to return */
223 if((ret_value = H5P_copy_plist(plist, TRUE)) < 0)
224 HGOTO_ERROR(H5E_INTERNAL, H5E_CANTINIT, FAIL, "unable to copy file creation properties")
225
226 done:
227 FUNC_LEAVE_API(ret_value)
228 } /* end H5Fget_create_plist() */
229
230
231 /*-------------------------------------------------------------------------
232 * Function: H5Fget_access_plist
233 *
234 * Purpose: Returns a copy of the file access property list of the
235 * specified file.
236 *
237 * NOTE: Make sure that, if you are going to overwrite
238 * information in the copied property list that was
239 * previously opened and assigned to the property list, then
240 * you must close it before overwriting the values.
241 *
242 * Return: Success: Object ID for a copy of the file access
243 * property list.
244 *
245 * Failure: FAIL
246 *
247 * Programmer: Robb Matzke
248 * Wednesday, February 18, 1998
249 *
250 *-------------------------------------------------------------------------
251 */
252 hid_t
H5Fget_access_plist(hid_t file_id)253 H5Fget_access_plist(hid_t file_id)
254 {
255 H5F_t *f; /* File info */
256 hid_t ret_value; /* Return value */
257
258 FUNC_ENTER_API(FAIL)
259 H5TRACE1("i", "i", file_id);
260
261 /* Check args */
262 if(NULL == (f = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
263 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file")
264
265 /* Retrieve the file's access property list */
266 if((ret_value = H5F_get_access_plist(f, TRUE)) < 0)
267 HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, FAIL, "can't get file access property list")
268
269 done:
270 FUNC_LEAVE_API(ret_value)
271 } /* end H5Fget_access_plist() */
272
273
274 /*-------------------------------------------------------------------------
275 * Function: H5Fget_obj_count
276 *
277 * Purpose: Public function returning the number of opened object IDs
278 * (files, datasets, groups and datatypes) in the same file.
279 *
280 * Return: Non-negative on success; negative on failure.
281 *
282 * Programmer: Raymond Lu
283 * Wednesday, Dec 5, 2001
284 *
285 *-------------------------------------------------------------------------
286 */
287 ssize_t
H5Fget_obj_count(hid_t file_id,unsigned types)288 H5Fget_obj_count(hid_t file_id, unsigned types)
289 {
290 H5F_t *f = NULL; /* File to query */
291 size_t obj_count = 0; /* Number of opened objects */
292 ssize_t ret_value; /* Return value */
293
294 FUNC_ENTER_API(FAIL)
295 H5TRACE2("Zs", "iIu", file_id, types);
296
297 /* Check arguments */
298 if(file_id != (hid_t)H5F_OBJ_ALL && (NULL == (f = (H5F_t *)H5I_object_verify(file_id, H5I_FILE))))
299 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file id")
300 if(0 == (types & H5F_OBJ_ALL))
301 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not an object type")
302
303 /* Perform the query */
304 if(H5F_get_obj_count(f, types, TRUE, &obj_count) < 0)
305 HGOTO_ERROR(H5E_INTERNAL, H5E_BADITER, FAIL, "H5F_get_obj_count failed")
306
307 /* Set the return value */
308 ret_value = (ssize_t)obj_count;
309
310 done:
311 FUNC_LEAVE_API(ret_value)
312 } /* end H5Fget_obj_count() */
313
314
315 /*-------------------------------------------------------------------------
316 * Function: H5Fget_object_ids
317 *
318 * Purpose: Public function to return a list of opened object IDs.
319 *
320 * Return: Non-negative on success; negative on failure.
321 *
322 * Programmer: Raymond Lu
323 * Wednesday, Dec 5, 2001
324 *
325 * Modification:
326 * Raymond Lu
327 * 24 September 2008
328 * Changed the return value to ssize_t and MAX_OBJTS to size_t to
329 * accommadate potential large number of objects.
330 *
331 *-------------------------------------------------------------------------
332 */
333 ssize_t
H5Fget_obj_ids(hid_t file_id,unsigned types,size_t max_objs,hid_t * oid_list)334 H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *oid_list)
335 {
336 H5F_t *f = NULL; /* File to query */
337 size_t obj_id_count = 0; /* Number of open objects */
338 ssize_t ret_value; /* Return value */
339
340 FUNC_ENTER_API(FAIL)
341 H5TRACE4("Zs", "iIuz*i", file_id, types, max_objs, oid_list);
342
343 /* Check arguments */
344 if(file_id != (hid_t)H5F_OBJ_ALL && (NULL == (f = (H5F_t *)H5I_object_verify(file_id, H5I_FILE))))
345 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file id")
346 if(0 == (types & H5F_OBJ_ALL))
347 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not an object type")
348 if(!oid_list)
349 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "object ID list is NULL")
350
351 /* Perform the query */
352 if(H5F_get_obj_ids(f, types, max_objs, oid_list, TRUE, &obj_id_count) < 0)
353 HGOTO_ERROR(H5E_INTERNAL, H5E_BADITER, FAIL, "H5F_get_obj_ids failed")
354
355 /* Set the return value */
356 ret_value = (ssize_t)obj_id_count;
357
358 done:
359 FUNC_LEAVE_API(ret_value)
360 } /* end H5Fget_obj_ids() */
361
362
363 /*-------------------------------------------------------------------------
364 * Function: H5Fget_vfd_handle
365 *
366 * Purpose: Returns a pointer to the file handle of the low-level file
367 * driver.
368 *
369 * Return: Success: non-negative value.
370 * Failure: negative.
371 *
372 * Programmer: Raymond Lu
373 * Sep. 16, 2002
374 *
375 *-------------------------------------------------------------------------
376 */
377 herr_t
H5Fget_vfd_handle(hid_t file_id,hid_t fapl,void ** file_handle)378 H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle)
379 {
380 H5F_t *file; /* File to query */
381 herr_t ret_value = SUCCEED; /* Return value */
382
383 FUNC_ENTER_API(FAIL)
384 H5TRACE3("e", "ii**x", file_id, fapl, file_handle);
385
386 /* Check args */
387 if(!file_handle)
388 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid file handle pointer")
389
390 /* Get the file */
391 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
392 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file id")
393
394 /* Retrieve the VFD handle for the file */
395 if(H5F_get_vfd_handle(file, fapl, file_handle) < 0)
396 HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "can't retrieve VFD handle")
397
398 done:
399 FUNC_LEAVE_API(ret_value)
400 } /* end H5Fget_vfd_handle() */
401
402
403 /*-------------------------------------------------------------------------
404 * Function: H5Fis_hdf5
405 *
406 * Purpose: Check the file signature to detect an HDF5 file.
407 *
408 * Bugs: This function is not robust: it only uses the default file
409 * driver when attempting to open the file when in fact it
410 * should use all known file drivers.
411 *
412 * Return: Success: TRUE/FALSE
413 *
414 * Failure: Negative
415 *
416 * Programmer: Unknown
417 *
418 * Modifications:
419 * Robb Matzke, 1999-08-02
420 * Rewritten to use the virtual file layer.
421 *-------------------------------------------------------------------------
422 */
423 htri_t
H5Fis_hdf5(const char * name)424 H5Fis_hdf5(const char *name)
425 {
426 htri_t ret_value; /* Return value */
427
428 FUNC_ENTER_API(FAIL)
429 H5TRACE1("t", "*s", name);
430
431 /* Check args and all the boring stuff. */
432 if(!name || !*name)
433 HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "no file name specified")
434
435 /* call the private is_HDF5 function */
436 if((ret_value = H5F_is_hdf5(name)) < 0)
437 HGOTO_ERROR(H5E_FILE, H5E_NOTHDF5, FAIL, "unable open file")
438
439 done:
440
441 FUNC_LEAVE_API(ret_value)
442 } /* end H5Fis_hdf5() */
443
444
445 /*-------------------------------------------------------------------------
446 * Function: H5Fcreate
447 *
448 * Purpose: This is the primary function for creating HDF5 files . The
449 * flags parameter determines whether an existing file will be
450 * overwritten or not. All newly created files are opened for
451 * both reading and writing. All flags may be combined with the
452 * bit-wise OR operator (`|') to change the behavior of the file
453 * create call.
454 *
455 * The more complex behaviors of a file's creation and access
456 * are controlled through the file-creation and file-access
457 * property lists. The value of H5P_DEFAULT for a template
458 * value indicates that the library should use the default
459 * values for the appropriate template.
460 *
461 * See also: H5Fpublic.h for the list of supported flags. H5Ppublic.h for
462 * the list of file creation and file access properties.
463 *
464 * Return: Success: A file ID
465 *
466 * Failure: FAIL
467 *
468 * Programmer: Unknown
469 *
470 *-------------------------------------------------------------------------
471 */
472 hid_t
H5Fcreate(const char * filename,unsigned flags,hid_t fcpl_id,hid_t fapl_id)473 H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)
474 {
475 H5F_t *new_file = NULL; /*file struct for new file */
476 hid_t ret_value; /*return value */
477
478 FUNC_ENTER_API(FAIL)
479 H5TRACE4("i", "*sIuii", filename, flags, fcpl_id, fapl_id);
480
481 /* Check/fix arguments */
482 if(!filename || !*filename)
483 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid file name")
484 /* In this routine, we only accept the following flags:
485 * H5F_ACC_EXCL and H5F_ACC_TRUNC
486 */
487 if(flags & ~(H5F_ACC_EXCL | H5F_ACC_TRUNC))
488 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid flags")
489 /* The H5F_ACC_EXCL and H5F_ACC_TRUNC flags are mutually exclusive */
490 if((flags & H5F_ACC_EXCL) && (flags & H5F_ACC_TRUNC))
491 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "mutually exclusive flags for file creation")
492
493 /* Check file creation property list */
494 if(H5P_DEFAULT == fcpl_id)
495 fcpl_id = H5P_FILE_CREATE_DEFAULT;
496 else
497 if(TRUE != H5P_isa_class(fcpl_id, H5P_FILE_CREATE))
498 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not file create property list")
499
500 /* Check the file access property list */
501 if(H5P_DEFAULT == fapl_id)
502 fapl_id = H5P_FILE_ACCESS_DEFAULT;
503 else
504 if(TRUE != H5P_isa_class(fapl_id, H5P_FILE_ACCESS))
505 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not file access property list")
506
507 /*
508 * Adjust bit flags by turning on the creation bit and making sure that
509 * the EXCL or TRUNC bit is set. All newly-created files are opened for
510 * reading and writing.
511 */
512 if (0==(flags & (H5F_ACC_EXCL|H5F_ACC_TRUNC)))
513 flags |= H5F_ACC_EXCL; /*default*/
514 flags |= H5F_ACC_RDWR | H5F_ACC_CREAT;
515
516 /*
517 * Create a new file or truncate an existing file.
518 */
519 if(NULL == (new_file = H5F_open(filename, flags, fcpl_id, fapl_id, H5AC_dxpl_id)))
520 HGOTO_ERROR(H5E_FILE, H5E_CANTOPENFILE, FAIL, "unable to create file")
521
522 /* Get an atom for the file */
523 if((ret_value = H5I_register(H5I_FILE, new_file, TRUE)) < 0)
524 HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "unable to atomize file")
525
526 /* Keep this ID in file object structure */
527 new_file->file_id = ret_value;
528
529 done:
530 if(ret_value < 0 && new_file)
531 if(H5F_close(new_file) < 0)
532 HDONE_ERROR(H5E_FILE, H5E_CANTCLOSEFILE, FAIL, "problems closing file")
533
534 FUNC_LEAVE_API(ret_value)
535 } /* end H5Fcreate() */
536
537
538 /*-------------------------------------------------------------------------
539 * Function: H5Fopen
540 *
541 * Purpose: This is the primary function for accessing existing HDF5
542 * files. The FLAGS argument determines whether writing to an
543 * existing file will be allowed or not. All flags may be
544 * combined with the bit-wise OR operator (`|') to change the
545 * behavior of the file open call. The more complex behaviors
546 * of a file's access are controlled through the file-access
547 * property list.
548 *
549 * See Also: H5Fpublic.h for a list of possible values for FLAGS.
550 *
551 * Return: Success: A file ID
552 *
553 * Failure: FAIL
554 *
555 * Programmer: Unknown
556 *
557 * Modifications:
558 * Robb Matzke, 1997-07-18
559 * File struct creation and destruction is through H5F_new() and
560 * H5F_dest(). Reading the root symbol table entry is done with
561 * H5G_decode().
562 *
563 * Robb Matzke, 1997-09-23
564 * Most of the work is now done by H5F_open() since H5Fcreate()
565 * and H5Fopen() originally contained almost identical code.
566 *
567 * Robb Matzke, 1998-02-18
568 * Added better error checking for the flags and the file access
569 * property list. It used to be possible to make the library
570 * dump core by passing an object ID that was not a file access
571 * property list.
572 *
573 * Robb Matzke, 1999-08-02
574 * The file access property list is passed to the H5F_open() as
575 * object IDs.
576 *-------------------------------------------------------------------------
577 */
578 hid_t
H5Fopen(const char * filename,unsigned flags,hid_t fapl_id)579 H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
580 {
581 H5F_t *new_file = NULL; /*file struct for new file */
582 hid_t ret_value; /*return value */
583
584 FUNC_ENTER_API(FAIL)
585 H5TRACE3("i", "*sIui", filename, flags, fapl_id);
586
587 /* Check/fix arguments. */
588 if(!filename || !*filename)
589 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid file name")
590 /* Reject undefined flags (~H5F_ACC_PUBLIC_FLAGS) and the H5F_ACC_TRUNC & H5F_ACC_EXCL flags */
591 if((flags & ~H5F_ACC_PUBLIC_FLAGS) ||
592 (flags & H5F_ACC_TRUNC) || (flags & H5F_ACC_EXCL))
593 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid file open flags")
594 if(H5P_DEFAULT == fapl_id)
595 fapl_id = H5P_FILE_ACCESS_DEFAULT;
596 else
597 if(TRUE != H5P_isa_class(fapl_id, H5P_FILE_ACCESS))
598 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not file access property list")
599
600 /* Open the file */
601 if(NULL == (new_file = H5F_open(filename, flags, H5P_FILE_CREATE_DEFAULT, fapl_id, H5AC_dxpl_id)))
602 HGOTO_ERROR(H5E_FILE, H5E_CANTOPENFILE, FAIL, "unable to open file")
603
604 /* Get an atom for the file */
605 if((ret_value = H5I_register(H5I_FILE, new_file, TRUE)) < 0)
606 HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "unable to atomize file handle")
607
608 /* Keep this ID in file object structure */
609 new_file->file_id = ret_value;
610
611 done:
612 if(ret_value < 0 && new_file && H5F_try_close(new_file) < 0)
613 HDONE_ERROR(H5E_FILE, H5E_CANTCLOSEFILE, FAIL, "problems closing file")
614
615 FUNC_LEAVE_API(ret_value)
616 } /* end H5Fopen() */
617
618
619 /*-------------------------------------------------------------------------
620 * Function: H5Fflush
621 *
622 * Purpose: Flushes all outstanding buffers of a file to disk but does
623 * not remove them from the cache. The OBJECT_ID can be a file,
624 * dataset, group, attribute, or named data type.
625 *
626 * Return: Non-negative on success/Negative on failure
627 *
628 * Programmer: Robb Matzke
629 * Thursday, August 6, 1998
630 *
631 *-------------------------------------------------------------------------
632 */
633 herr_t
H5Fflush(hid_t object_id,H5F_scope_t scope)634 H5Fflush(hid_t object_id, H5F_scope_t scope)
635 {
636 H5F_t *f = NULL; /* File to flush */
637 H5O_loc_t *oloc = NULL; /* Object location for ID */
638 herr_t ret_value = SUCCEED; /* Return value */
639
640 FUNC_ENTER_API(FAIL)
641 H5TRACE2("e", "iFs", object_id, scope);
642
643 switch(H5I_get_type(object_id)) {
644 case H5I_FILE:
645 if(NULL == (f = (H5F_t *)H5I_object(object_id)))
646 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid file identifier")
647 break;
648
649 case H5I_GROUP:
650 {
651 H5G_t *grp;
652
653 if(NULL == (grp = (H5G_t *)H5I_object(object_id)))
654 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid group identifier")
655 oloc = H5G_oloc(grp);
656 }
657 break;
658
659 case H5I_DATATYPE:
660 {
661 H5T_t *type;
662
663 if(NULL == (type = (H5T_t *)H5I_object(object_id)))
664 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid type identifier")
665 oloc = H5T_oloc(type);
666 }
667 break;
668
669 case H5I_DATASET:
670 {
671 H5D_t *dset;
672
673 if(NULL == (dset = (H5D_t *)H5I_object(object_id)))
674 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid dataset identifier")
675 oloc = H5D_oloc(dset);
676 }
677 break;
678
679 case H5I_ATTR:
680 {
681 H5A_t *attr;
682
683 if(NULL == (attr = (H5A_t *)H5I_object(object_id)))
684 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid attribute identifier")
685 oloc = H5A_oloc(attr);
686 }
687 break;
688
689 case H5I_UNINIT:
690 case H5I_BADID:
691 case H5I_DATASPACE:
692 case H5I_REFERENCE:
693 case H5I_VFL:
694 case H5I_GENPROP_CLS:
695 case H5I_GENPROP_LST:
696 case H5I_ERROR_CLASS:
697 case H5I_ERROR_MSG:
698 case H5I_ERROR_STACK:
699 case H5I_NTYPES:
700 default:
701 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file or file object")
702 } /* end switch */
703
704 if(!f) {
705 if(!oloc)
706 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "object is not associated with a file")
707 f = oloc->file;
708 } /* end if */
709 if(!f)
710 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "object is not associated with a file")
711
712 /* Flush the file */
713 /*
714 * Nothing to do if the file is read only. This determination is
715 * made at the shared open(2) flags level, implying that opening a
716 * file twice, once for read-only and once for read-write, and then
717 * calling H5Fflush() with the read-only handle, still causes data
718 * to be flushed.
719 */
720 if(H5F_ACC_RDWR & H5F_INTENT(f)) {
721 /* Flush other files, depending on scope */
722 if(H5F_SCOPE_GLOBAL == scope) {
723 /* Call the flush routine for mounted file hierarchies */
724 if(H5F_flush_mounts(f, H5AC_dxpl_id) < 0)
725 HGOTO_ERROR(H5E_FILE, H5E_CANTFLUSH, FAIL, "unable to flush mounted file hierarchy")
726 } /* end if */
727 else {
728 /* Call the flush routine, for this file */
729 if(H5F_flush(f, H5AC_dxpl_id, FALSE) < 0)
730 HGOTO_ERROR(H5E_FILE, H5E_CANTFLUSH, FAIL, "unable to flush file's cached information")
731 } /* end else */
732 } /* end if */
733
734 done:
735 FUNC_LEAVE_API(ret_value)
736 } /* end H5Fflush() */
737
738
739 /*-------------------------------------------------------------------------
740 * Function: H5Fclose
741 *
742 * Purpose: This function closes the file specified by FILE_ID by
743 * flushing all data to storage, and terminating access to the
744 * file through FILE_ID. If objects (e.g., datasets, groups,
745 * etc.) are open in the file then the underlying storage is not
746 * closed until those objects are closed; however, all data for
747 * the file and the open objects is flushed.
748 *
749 * Return: Success: Non-negative
750 *
751 * Failure: Negative
752 *
753 * Programmer: Robb Matzke
754 * Saturday, February 20, 1999
755 *
756 * Modifications:
757 *
758 *-------------------------------------------------------------------------
759 */
760 herr_t
H5Fclose(hid_t file_id)761 H5Fclose(hid_t file_id)
762 {
763 H5F_t *f = NULL;
764 int nref;
765 herr_t ret_value = SUCCEED;
766
767 FUNC_ENTER_API(FAIL)
768 H5TRACE1("e", "i", file_id);
769
770 /* Check/fix arguments. */
771 if(H5I_FILE != H5I_get_type(file_id))
772 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file ID")
773
774 /* Flush file if this is the last reference to this id and we have write
775 * intent, unless it will be flushed by the "shared" file being closed.
776 * This is only necessary to replicate previous behaviour, and could be
777 * disabled by an option/property to improve performance. */
778 if(NULL == (f = (H5F_t *)H5I_object(file_id)))
779 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid file identifier")
780 if((f->shared->nrefs > 1) && (H5F_INTENT(f) & H5F_ACC_RDWR)) {
781 if((nref = H5I_get_ref(file_id, FALSE)) < 0)
782 HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, FAIL, "can't get ID ref count")
783 if(nref == 1)
784 if(H5F_flush(f, H5AC_dxpl_id, FALSE) < 0)
785 HGOTO_ERROR(H5E_CACHE, H5E_CANTFLUSH, FAIL, "unable to flush cache")
786 } /* end if */
787
788 /*
789 * Decrement reference count on atom. When it reaches zero the file will
790 * be closed.
791 */
792 if(H5I_dec_app_ref(file_id) < 0)
793 HGOTO_ERROR(H5E_ATOM, H5E_CANTCLOSEFILE, FAIL, "decrementing file ID failed")
794
795 done:
796 FUNC_LEAVE_API(ret_value)
797 } /* end H5Fclose() */
798
799
800 /*-------------------------------------------------------------------------
801 * Function: H5Freopen
802 *
803 * Purpose: Reopen a file. The new file handle which is returned points
804 * to the same file as the specified file handle. Both handles
805 * share caches and other information. The only difference
806 * between the handles is that the new handle is not mounted
807 * anywhere and no files are mounted on it.
808 *
809 * Return: Success: New file ID
810 *
811 * Failure: FAIL
812 *
813 * Programmer: Robb Matzke
814 * Friday, October 16, 1998
815 *
816 *-------------------------------------------------------------------------
817 */
818 hid_t
H5Freopen(hid_t file_id)819 H5Freopen(hid_t file_id)
820 {
821 H5F_t *old_file = NULL;
822 H5F_t *new_file = NULL;
823 hid_t ret_value;
824
825 FUNC_ENTER_API(FAIL)
826 H5TRACE1("i", "i", file_id);
827
828 /* Check arguments */
829 if(NULL == (old_file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
830 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file")
831
832 /* Get a new "top level" file struct, sharing the same "low level" file struct */
833 if(NULL == (new_file = H5F_new(old_file->shared, 0, H5P_FILE_CREATE_DEFAULT, H5P_FILE_ACCESS_DEFAULT, NULL)))
834 HGOTO_ERROR(H5E_FILE, H5E_CANTINIT, FAIL, "unable to reopen file")
835
836 /* Duplicate old file's names */
837 new_file->open_name = H5MM_xstrdup(old_file->open_name);
838 new_file->actual_name = H5MM_xstrdup(old_file->actual_name);
839 new_file->extpath = H5MM_xstrdup(old_file->extpath);
840
841 if((ret_value = H5I_register(H5I_FILE, new_file, TRUE)) < 0)
842 HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "unable to atomize file handle")
843
844 /* Keep this ID in file object structure */
845 new_file->file_id = ret_value;
846
847 done:
848 if(ret_value < 0 && new_file)
849 if(H5F_dest(new_file, H5AC_dxpl_id, FALSE) < 0)
850 HDONE_ERROR(H5E_FILE, H5E_CANTCLOSEFILE, FAIL, "can't close file")
851
852 FUNC_LEAVE_API(ret_value)
853 } /* end H5Freopen() */
854
855
856 /*-------------------------------------------------------------------------
857 * Function: H5Fget_intent
858 *
859 * Purpose: Public API to retrieve the file's 'intent' flags passed
860 * during H5Fopen()
861 *
862 * Return: Non-negative on success/negative on failure
863 *
864 * Programmer: James Laird
865 * August 23, 2006
866 *
867 *-------------------------------------------------------------------------
868 */
869 herr_t
H5Fget_intent(hid_t file_id,unsigned * intent_flags)870 H5Fget_intent(hid_t file_id, unsigned *intent_flags)
871 {
872 herr_t ret_value = SUCCEED;
873
874 FUNC_ENTER_API(FAIL)
875 H5TRACE2("e", "i*Iu", file_id, intent_flags);
876
877 /* If no intent flags were passed in, exit quietly */
878 if(intent_flags) {
879 H5F_t * file; /* Pointer to file structure */
880
881 /* Get the internal file structure */
882 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
883 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file")
884
885 /* HDF5 uses some flags internally that users don't know about.
886 * Simplify things for them so that they only get either H5F_ACC_RDWR
887 * or H5F_ACC_RDONLY.
888 */
889 if(H5F_INTENT(file) & H5F_ACC_RDWR)
890 *intent_flags = H5F_ACC_RDWR;
891 else
892 *intent_flags = H5F_ACC_RDONLY;
893 } /* end if */
894
895 done:
896 FUNC_LEAVE_API(ret_value)
897 } /* end H5Fget_intent() */
898
899
900 /*-------------------------------------------------------------------------
901 * Function: H5Fget_freespace
902 *
903 * Purpose: Retrieves the amount of free space in the file.
904 *
905 * Return: Success: Amount of free space for type
906 * Failure: Negative
907 *
908 * Programmer: Quincey Koziol
909 * koziol@ncsa.uiuc.edu
910 * Oct 6, 2003
911 *
912 *-------------------------------------------------------------------------
913 */
914 hssize_t
H5Fget_freespace(hid_t file_id)915 H5Fget_freespace(hid_t file_id)
916 {
917 H5F_t *file; /* File object for file ID */
918 hsize_t tot_space; /* Amount of free space in the file */
919 hssize_t ret_value; /* Return value */
920
921 FUNC_ENTER_API(FAIL)
922 H5TRACE1("Hs", "i", file_id);
923
924 /* Check args */
925 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
926 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
927
928 /* Go get the actual amount of free space in the file */
929 if(H5MF_get_freespace(file, H5AC_ind_dxpl_id, &tot_space, NULL) < 0)
930 HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "unable to check free space for file")
931
932 ret_value = (hssize_t)tot_space;
933
934 done:
935 FUNC_LEAVE_API(ret_value)
936 } /* end H5Fget_freespace() */
937
938
939 /*-------------------------------------------------------------------------
940 * Function: H5Fget_filesize
941 *
942 * Purpose: Retrieves the file size of the HDF5 file. This function
943 * is called after an existing file is opened in order
944 * to learn the true size of the underlying file.
945 *
946 * Return: Success: Non-negative
947 * Failure: Negative
948 *
949 * Programmer: David Pitt
950 * david.pitt@bigpond.com
951 * Apr 27, 2004
952 *
953 *-------------------------------------------------------------------------
954 */
955 herr_t
H5Fget_filesize(hid_t file_id,hsize_t * size)956 H5Fget_filesize(hid_t file_id, hsize_t *size)
957 {
958 H5F_t *file; /* File object for file ID */
959 haddr_t eof; /* End of file address */
960 haddr_t base_addr; /* Base address for the file */
961 herr_t ret_value = SUCCEED; /* Return value */
962
963 FUNC_ENTER_API(FAIL)
964 H5TRACE2("e", "i*h", file_id, size);
965
966 /* Check args */
967 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
968 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
969
970 /* Go get the actual file size */
971 if(HADDR_UNDEF == (eof = H5FD_get_eof(file->shared->lf)))
972 HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "unable to get file size")
973 base_addr = H5FD_get_base_addr(file->shared->lf);
974
975 if(size)
976 *size = (hsize_t)(eof + base_addr); /* Convert relative base address for file to absolute address */
977
978 done:
979 FUNC_LEAVE_API(ret_value)
980 } /* end H5Fget_filesize() */
981
982
983 /*-------------------------------------------------------------------------
984 * Function: H5Fget_file_image
985 *
986 * Purpose: If a buffer is provided (via the buf_ptr argument) and is
987 * big enough (size in buf_len argument), load *buf_ptr with
988 * an image of the open file whose ID is provided in the
989 * file_id parameter, and return the number of bytes copied
990 * to the buffer.
991 *
992 * If the buffer exists, but is too small to contain an image
993 * of the indicated file, return a negative number.
994 *
995 * Finally, if no buffer is provided, return the size of the
996 * buffer needed. This value is simply the eoa of the target
997 * file.
998 *
999 * Note that any user block is skipped.
1000 *
1001 * Also note that the function may not be used on files
1002 * opened with either the split/multi file driver or the
1003 * family file driver.
1004 *
1005 * In the former case, the sparse address space makes the
1006 * get file image operation impractical, due to the size of
1007 * the image typically required.
1008 *
1009 * In the case of the family file driver, the problem is
1010 * the driver message in the super block, which will prevent
1011 * the image being opened with any driver other than the
1012 * family file driver -- which negates the purpose of the
1013 * operation. This can be fixed, but no resources for
1014 * this now.
1015 *
1016 * Return: Success: Bytes copied / number of bytes needed.
1017 * Failure: negative value
1018 *
1019 * Programmer: John Mainzer
1020 * 11/15/11
1021 *
1022 *-------------------------------------------------------------------------
1023 */
1024 ssize_t
H5Fget_file_image(hid_t file_id,void * buf_ptr,size_t buf_len)1025 H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len)
1026 {
1027 H5F_t *file; /* File object for file ID */
1028 ssize_t ret_value; /* Return value */
1029
1030 FUNC_ENTER_API(FAIL)
1031 H5TRACE3("Zs", "i*xz", file_id, buf_ptr, buf_len);
1032
1033 /* Check args */
1034 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
1035 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
1036
1037 /* call private get_file_image function */
1038 if((ret_value = H5F_get_file_image(file, buf_ptr, buf_len)) < 0)
1039 HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "unable to get file image")
1040
1041 done:
1042 FUNC_LEAVE_API(ret_value)
1043 } /* H5Fget_file_image() */
1044
1045
1046 /*-------------------------------------------------------------------------
1047 * Function: H5Fget_mdc_config
1048 *
1049 * Purpose: Retrieves the current automatic cache resize configuration
1050 * from the metadata cache, and return it in *config_ptr.
1051 *
1052 * Note that the version field of *config_Ptr must be correctly
1053 * filled in by the caller. This allows us to adapt for
1054 * obsolete versions of the structure.
1055 *
1056 * Return: Success: SUCCEED
1057 * Failure: FAIL
1058 *
1059 * Programmer: John Mainzer
1060 * 3/24/05
1061 *
1062 *-------------------------------------------------------------------------
1063 */
1064 herr_t
H5Fget_mdc_config(hid_t file_id,H5AC_cache_config_t * config_ptr)1065 H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr)
1066 {
1067 H5F_t *file; /* File object for file ID */
1068 herr_t ret_value = SUCCEED; /* Return value */
1069
1070 FUNC_ENTER_API(FAIL)
1071 H5TRACE2("e", "i*x", file_id, config_ptr);
1072
1073 /* Check args */
1074 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
1075 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
1076 if((NULL == config_ptr) || (config_ptr->version != H5AC__CURR_CACHE_CONFIG_VERSION))
1077 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "Bad config_ptr")
1078
1079 /* Go get the resize configuration */
1080 if(H5AC_get_cache_auto_resize_config(file->shared->cache, config_ptr) < 0)
1081 HGOTO_ERROR(H5E_CACHE, H5E_SYSTEM, FAIL, "H5AC_get_cache_auto_resize_config() failed.")
1082
1083 done:
1084 FUNC_LEAVE_API(ret_value)
1085 } /* H5Fget_mdc_config() */
1086
1087
1088 /*-------------------------------------------------------------------------
1089 * Function: H5Fset_mdc_config
1090 *
1091 * Purpose: Sets the current metadata cache automatic resize
1092 * configuration, using the contents of the instance of
1093 * H5AC_cache_config_t pointed to by config_ptr.
1094 *
1095 * Return: Success: SUCCEED
1096 * Failure: FAIL
1097 *
1098 * Programmer: John Mainzer
1099 * 3/24/05
1100 *
1101 *-------------------------------------------------------------------------
1102 */
1103 herr_t
H5Fset_mdc_config(hid_t file_id,H5AC_cache_config_t * config_ptr)1104 H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr)
1105 {
1106 H5F_t *file; /* File object for file ID */
1107 herr_t ret_value = SUCCEED; /* Return value */
1108
1109 FUNC_ENTER_API(FAIL)
1110 H5TRACE2("e", "i*x", file_id, config_ptr);
1111
1112 /* Check args */
1113 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
1114 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
1115
1116 /* set the resize configuration */
1117 if(H5AC_set_cache_auto_resize_config(file->shared->cache, config_ptr) < 0)
1118 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "H5AC_set_cache_auto_resize_config() failed.")
1119
1120 done:
1121 FUNC_LEAVE_API(ret_value)
1122 } /* H5Fset_mdc_config() */
1123
1124
1125 /*-------------------------------------------------------------------------
1126 * Function: H5Fget_mdc_hit_rate
1127 *
1128 * Purpose: Retrieves the current hit rate from the metadata cache.
1129 * This rate is the overall hit rate since the last time
1130 * the hit rate statistics were reset either manually or
1131 * automatically.
1132 *
1133 * Return: Success: SUCCEED
1134 * Failure: FAIL
1135 *
1136 * Programmer: John Mainzer
1137 * 3/24/05
1138 *
1139 *-------------------------------------------------------------------------
1140 */
1141 herr_t
H5Fget_mdc_hit_rate(hid_t file_id,double * hit_rate_ptr)1142 H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr)
1143 {
1144 H5F_t *file; /* File object for file ID */
1145 herr_t ret_value = SUCCEED; /* Return value */
1146
1147 FUNC_ENTER_API(FAIL)
1148 H5TRACE2("e", "i*d", file_id, hit_rate_ptr);
1149
1150 /* Check args */
1151 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
1152 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
1153
1154 if(NULL == hit_rate_ptr)
1155 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL hit rate pointer")
1156
1157 /* Go get the current hit rate */
1158 if(H5AC_get_cache_hit_rate(file->shared->cache, hit_rate_ptr) < 0)
1159 HGOTO_ERROR(H5E_CACHE, H5E_SYSTEM, FAIL, "H5AC_get_cache_hit_rate() failed.")
1160
1161 done:
1162 FUNC_LEAVE_API(ret_value)
1163 } /* H5Fget_mdc_hit_rate() */
1164
1165
1166 /*-------------------------------------------------------------------------
1167 * Function: H5Fget_mdc_size
1168 *
1169 * Purpose: Retrieves the maximum size, minimum clean size, current
1170 * size, and current number of entries from the metadata
1171 * cache associated with the specified file. If any of
1172 * the ptr parameters are NULL, the associated datum is
1173 * not returned.
1174 *
1175 * Return: Success: SUCCEED
1176 * Failure: FAIL
1177 *
1178 * Programmer: John Mainzer
1179 * 3/24/05
1180 *
1181 *-------------------------------------------------------------------------
1182 */
1183 herr_t
H5Fget_mdc_size(hid_t file_id,size_t * max_size_ptr,size_t * min_clean_size_ptr,size_t * cur_size_ptr,int * cur_num_entries_ptr)1184 H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr,
1185 size_t *cur_size_ptr, int *cur_num_entries_ptr)
1186 {
1187 H5F_t *file; /* File object for file ID */
1188 int32_t cur_num_entries;
1189 herr_t ret_value = SUCCEED; /* Return value */
1190
1191 FUNC_ENTER_API(FAIL)
1192 H5TRACE5("e", "i*z*z*z*Is", file_id, max_size_ptr, min_clean_size_ptr,
1193 cur_size_ptr, cur_num_entries_ptr);
1194
1195 /* Check args */
1196 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
1197 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
1198
1199 /* Go get the size data */
1200 if(H5AC_get_cache_size(file->shared->cache, max_size_ptr,
1201 min_clean_size_ptr, cur_size_ptr, &cur_num_entries) < 0)
1202 HGOTO_ERROR(H5E_CACHE, H5E_SYSTEM, FAIL, "H5AC_get_cache_size() failed.")
1203
1204 if(cur_num_entries_ptr != NULL)
1205 *cur_num_entries_ptr = (int)cur_num_entries;
1206
1207 done:
1208 FUNC_LEAVE_API(ret_value)
1209 } /* H5Fget_mdc_size() */
1210
1211
1212 /*-------------------------------------------------------------------------
1213 * Function: H5Freset_mdc_hit_rate_stats
1214 *
1215 * Purpose: Reset the hit rate statistic whose current value can
1216 * be obtained via the H5Fget_mdc_hit_rate() call. Note
1217 * that this statistic will also be reset once per epoch
1218 * by the automatic cache resize code if it is enabled.
1219 *
1220 * It is probably a bad idea to call this function unless
1221 * you are controlling cache size from your program instead
1222 * of using our cache size control code.
1223 *
1224 * Return: Success: SUCCEED
1225 * Failure: FAIL
1226 *
1227 * Programmer: John Mainzer
1228 * 3/24/05
1229 *
1230 *-------------------------------------------------------------------------
1231 */
1232 herr_t
H5Freset_mdc_hit_rate_stats(hid_t file_id)1233 H5Freset_mdc_hit_rate_stats(hid_t file_id)
1234 {
1235 H5F_t *file; /* File object for file ID */
1236 herr_t ret_value = SUCCEED; /* Return value */
1237
1238 FUNC_ENTER_API(FAIL)
1239 H5TRACE1("e", "i", file_id);
1240
1241 /* Check args */
1242 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
1243 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
1244
1245 /* Reset the hit rate statistic */
1246 if(H5AC_reset_cache_hit_rate_stats(file->shared->cache) < 0)
1247 HGOTO_ERROR(H5E_CACHE, H5E_SYSTEM, FAIL, "can't reset cache hit rate")
1248
1249 done:
1250 FUNC_LEAVE_API(ret_value)
1251 } /* H5Freset_mdc_hit_rate_stats() */
1252
1253
1254 /*-------------------------------------------------------------------------
1255 * Function: H5Fget_name
1256 *
1257 * Purpose: Gets the name of the file to which object OBJ_ID belongs.
1258 * If `name' is non-NULL then write up to `size' bytes into that
1259 * buffer and always return the length of the entry name.
1260 * Otherwise `size' is ignored and the function does not store the name,
1261 * just returning the number of characters required to store the name.
1262 * If an error occurs then the buffer pointed to by `name' (NULL or non-NULL)
1263 * is unchanged and the function returns a negative value.
1264 *
1265 * Note: This routine returns the name that was used to open the file,
1266 * not the actual name after resolving symlinks, etc.
1267 *
1268 * Return: Success: The length of the file name
1269 * Failure: Negative
1270 *
1271 * Programmer: Raymond Lu
1272 * June 29, 2004
1273 *
1274 *-------------------------------------------------------------------------
1275 */
1276 ssize_t
H5Fget_name(hid_t obj_id,char * name,size_t size)1277 H5Fget_name(hid_t obj_id, char *name/*out*/, size_t size)
1278 {
1279 H5F_t *f; /* Top file in mount hierarchy */
1280 size_t len;
1281 ssize_t ret_value;
1282
1283 FUNC_ENTER_API(FAIL)
1284 H5TRACE3("Zs", "ixz", obj_id, name, size);
1285
1286 /* For file IDs, get the file object directly */
1287 /* (This prevents the H5G_loc() call from returning the file pointer for
1288 * the top file in a mount hierarchy)
1289 */
1290 if(H5I_get_type(obj_id) == H5I_FILE ) {
1291 if(NULL == (f = (H5F_t *)H5I_object(obj_id)))
1292 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file")
1293 } /* end if */
1294 else {
1295 H5G_loc_t loc; /* Object location */
1296
1297 /* Get symbol table entry */
1298 if(H5G_loc(obj_id, &loc) < 0)
1299 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a valid object ID")
1300 f = loc.oloc->file;
1301 } /* end else */
1302
1303 len = HDstrlen(H5F_OPEN_NAME(f));
1304
1305 if(name) {
1306 HDstrncpy(name, H5F_OPEN_NAME(f), MIN(len + 1,size));
1307 if(len >= size)
1308 name[size-1]='\0';
1309 } /* end if */
1310
1311 /* Set return value */
1312 ret_value = (ssize_t)len;
1313
1314 done:
1315 FUNC_LEAVE_API(ret_value)
1316 } /* end H5Fget_name() */
1317
1318
1319 /*-------------------------------------------------------------------------
1320 * Function: H5Fget_info
1321 * 1. Get storage size for superblock extension if there is one
1322 * 2. Get the amount of btree and heap storage for entries
1323 * in the SOHM table if there is one.
1324 * Consider success when there is no superblock extension and/or SOHM table
1325 *
1326 * Return: Success: non-negative on success
1327 * Failure: Negative
1328 *
1329 * Programmer: Vailin Choi
1330 * July 11, 2007
1331 *
1332 *-------------------------------------------------------------------------
1333 */
1334 herr_t
H5Fget_info(hid_t obj_id,H5F_info_t * finfo)1335 H5Fget_info(hid_t obj_id, H5F_info_t *finfo)
1336 {
1337 H5F_t *f; /* Top file in mount hierarchy */
1338 herr_t ret_value = SUCCEED; /* Return value */
1339
1340 FUNC_ENTER_API(FAIL)
1341 H5TRACE2("e", "i*x", obj_id, finfo);
1342
1343 /* Check args */
1344 if(!finfo)
1345 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no info struct")
1346
1347 /* For file IDs, get the file object directly */
1348 /* (This prevents the H5G_loc() call from returning the file pointer for
1349 * the top file in a mount hierarchy)
1350 */
1351 if(H5I_get_type(obj_id) == H5I_FILE ) {
1352 if(NULL == (f = (H5F_t *)H5I_object(obj_id)))
1353 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file")
1354 } /* end if */
1355 else {
1356 H5G_loc_t loc; /* Object location */
1357
1358 /* Get symbol table entry */
1359 if(H5G_loc(obj_id, &loc) < 0)
1360 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a valid object ID")
1361 f = loc.oloc->file;
1362 } /* end else */
1363 HDassert(f->shared);
1364
1365 /* Reset file info struct */
1366 HDmemset(finfo, 0, sizeof(H5F_info_t));
1367
1368 /* Check for superblock extension info */
1369 if(H5F_super_size(f, H5AC_ind_dxpl_id, NULL, &finfo->super_ext_size) < 0)
1370 HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "Unable to retrieve superblock extension size")
1371
1372 /* Check for SOHM info */
1373 if(H5F_addr_defined(f->shared->sohm_addr))
1374 if(H5SM_ih_size(f, H5AC_ind_dxpl_id, finfo) < 0)
1375 HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "Unable to retrieve SOHM btree & heap storage info")
1376
1377 done:
1378 FUNC_LEAVE_API(ret_value)
1379 } /* end H5Fget_info() */
1380
1381
1382 /*-------------------------------------------------------------------------
1383 * Function: H5Fclear_elink_file_cache
1384 *
1385 * Purpose: Releases the external file cache associated with the
1386 * provided file, potentially closing any cached files
1387 * unless they are held open from somewhere\ else.
1388 *
1389 * Return: Success: non-negative
1390 * Failure: negative
1391 *
1392 * Programmer: Neil Fortner; December 30, 2010
1393 *
1394 *-------------------------------------------------------------------------
1395 */
1396 herr_t
H5Fclear_elink_file_cache(hid_t file_id)1397 H5Fclear_elink_file_cache(hid_t file_id)
1398 {
1399 H5F_t *file; /* File */
1400 herr_t ret_value = SUCCEED; /* Return value */
1401
1402 FUNC_ENTER_API(FAIL)
1403 H5TRACE1("e", "i", file_id);
1404
1405 /* Check args */
1406 if(NULL == (file = (H5F_t *)H5I_object_verify(file_id, H5I_FILE)))
1407 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID")
1408
1409 /* Release the EFC */
1410 if(file->shared->efc)
1411 if(H5F_efc_release(file->shared->efc) < 0)
1412 HGOTO_ERROR(H5E_FILE, H5E_CANTRELEASE, FAIL, "can't release external file cache")
1413
1414 done:
1415 FUNC_LEAVE_API(ret_value)
1416 } /* end H5Fclear_elink_file_cache() */
1417