From 019ab202756eeaa92485eca955d2d86e4cb48d43 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Wed, 5 Dec 2001 17:08:37 -0500 Subject: [svn-r4678] Purpose: Expanded descriptions and minor copy edits. Description: H5Fcreate, H5Fopen, H5Fclose Changes stemming from Albert's H5Fxxx proposal Added IN/OUT designations to parameters. Minor formatting and copy edits [Sorry, but "no space left on device" error prevents deletion of extra blank lines!] Platforms tested: IE 5 --- doc/html/RM_H5F.html | 172 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 123 insertions(+), 49 deletions(-) diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html index fbcbcc2..e01da01 100644 --- a/doc/html/RM_H5F.html +++ b/doc/html/RM_H5F.html @@ -135,45 +135,72 @@ facilitate moving easily between them. function for accessing existing HDF5 files.

The parameter access_id is a file access property - list identifier or H5P_DEFAULT for the default I/O access - parameters. + list identifier or H5P_DEFAULT if the + default I/O access parameters are to be used

The flags argument determines whether writing - to an existing file will be allowed or not. + to an existing file will be allowed. The file is opened with read and write permission if - flags is set to H5F_ACC_RDWR. + flags is set to H5F_ACC_RDWR. All flags may be combined with the bit-wise OR operator (`|') - to change the behavior of the file open call. - The more complex behaviors of a file's access are controlled - through the file-access property list. + to change the behavior of the file open call. + More complex behaviors of file access are controlled + through the file-access property list.

- Files which are opened more than once return a unique identifier - for each H5Fopen() call and can be accessed - through all file identifiers. + The return value is a file identifier for the open file; + this file identifier should be closed by calling + H5Fclose when it is no longer needed.

- The return value is a file identifier for the open file and it - should be closed by calling H5Fclose() when it is - no longer needed. + + Special case -- Multiple opens: +
+ A file can often be opened with a new H5Fopen + call without closing an already-open identifier established + in a previous H5Fopen or H5Fcreate + call. Each such H5Fopen call will return a + unique identifier and the file can be accessed through any + of these identifiers as long as the identifier remains valid. + In such multiply-opened cases, all the open calls should + use the same flags argument. +

+ In some cases, such as files on a local Unix file system, + the HDF5 library can detect that a file is multiply opened and + will maintain coherent access among the file identifiers. +

+ But in many other cases, such as parallel file systems or + networked file systems, it is not always possible to detect + multiple opens of the same physical file. + In such cases, HDF5 will treat the file identifiers + as though they are accessing different files and + will be unable to maintain coherent access. + Errors are likely to result in these cases. + While unlikely, the HDF5 library may not be able to detect, + and thus report, such errors. +

+ It is generally recommended that applications avoid + multiple opens of the same file. +

Parameters:
const char *name -
Name of the file to access. +
IN: Name of the file to access.
unsigned flags -
File access flags. Allowable values are: +
IN: File access flags. Allowable values are:
    -
    H5F_ACC_RDWR +
    H5F_ACC_RDWR
    Allow read and write access to file. -
    H5F_ACC_RDONLY +
    H5F_ACC_RDONLY
    Allow read-only access to file. -
+
  • H5F_ACC_RDWR and H5F_ACC_RDONLY are mutually exclusive; use exactly one.
  • An additional flag, H5F_ACC_DEBUG, prints debug information. This flag is used only by HDF5 library developers; it is neither tested nor supported for use in applications. +
    hid_t access_id -
    Identifier for the file access properties list. +
    IN: Identifier for the file access properties list. If parallel file access is desired, this is a collective call according to the communicator stored in the access_id. @@ -218,17 +245,55 @@ facilitate moving easily between them. property lists. The value of H5P_DEFAULT for a property list value indicates that the library should use the default values for the appropriate property list. +

    + The return value is a file identifier for the newly-created file; + this file identifier should be closed by calling + H5Fclose when it is no longer needed. +

    + + Special case -- File creation in the case of an + already-open file: +
    + If a file being created is already opened, by either a + previous H5Fopen or H5Fcreate call, + the HDF5 library may or may not detect that the open file and + the new file are the same physical file. + (See H5Fopen regarding + the limitations in detecting the re-opening of an already-open + file.) +

    + If the library detects that the file is already opened, + H5Fcreate will return a failure, regardless + of the use of H5F_ACC_TRUNC. +

    + If the library does not detect that the file is already opened + and H5F_ACC_TRUNC is not used, + H5Fcreate will return a failure because the file + already exists. Note that this is correct behavior. +

    + But if the library does not detect that the file is already + opened and H5F_ACC_TRUNC is used, + H5Fcreate will truncate the existing file + and return a valid file identifier. + Such a truncation of a currently-opened file will almost + certainly result in errors. + While unlikely, the HDF5 library may not be able to detect, + and thus report, such errors. +

    + Applications should avoid calling H5Fcreate + with an already opened file. +

    Parameters:
    const char *name -
    Name of the file to access. +
    IN: Name of the file to access.
    uintn flags -
    File access flags. Allowable values are: +
    IN: File access flags. Allowable values are:
      -
      H5F_ACC_TRUNC +
      H5F_ACC_TRUNC
      Truncate file, if it already exists, erasing all data previously stored in the file. -
      H5F_ACC_EXCL +
      H5F_ACC_EXCL
      Fail if file already exists.
  • H5F_ACC_TRUNC and H5F_ACC_EXCL @@ -238,11 +303,11 @@ facilitate moving easily between them. developers; it is neither tested nor supported for use in applications.
    hid_t create_id -
    File creation property list identifier, used when modifying +
    IN: File creation property list identifier, used when modifying default file meta-data. Use H5P_DEFAULT for default file creation properties.
    hid_t access_id -
    File access property list identifier. +
    IN: File access property list identifier. If parallel file access is desired, this is a collective call according to the communicator stored in the access_id. @@ -300,9 +365,9 @@ facilitate moving easily between them.
    Parameters:
    hid_t object_id -
    Identifier of object used to identify the file. +
    IN: Identifier of object used to identify the file.
    H5F_scope_t scope -
    Specifies the scope of the flushing action. +
    IN: Specifies the scope of the flushing action.
    Returns:
    Returns a non-negative value if successful; @@ -332,7 +397,7 @@ facilitate moving easily between them.
    Parameters:
    const char *name -
    File name to check format. +
    IN: File name to check format.
    Returns:
    When successful, returns a positive value, for TRUE, @@ -372,7 +437,7 @@ facilitate moving easily between them.
    Parameters:
    hid_t file_id -
    Identifier of the file to get creation property list of +
    IN: Identifier of the file to get creation property list of
    Returns:
    Returns a file creation property list identifier if successful; @@ -409,7 +474,7 @@ facilitate moving easily between them.
    Parameters:
    hid_t file_id -
    Identifier of file to get access property list of +
    IN: Identifier of file to get access property list of
    Returns:
    Returns a file access property list identifier if successful; @@ -443,15 +508,8 @@ facilitate moving easily between them. identifier, group identifier, or shared datatype identifier), the file will be fully closed and access will end.

    - If this is the last file identifier open for the file - and other access identifiers are still in use, - those access identifiers remain valid until separately - closed and can still be used. - (But the file identifier is no longer valid and cannot be used.) - Once all of the remaining access identifiers are closed, - the file will be fully closed and access will end. -

    - EXCEPTION: + Delayed close: +
    Note the following deviation from the above-described behavior. If H5Fclose is called for a file but one or more objects within the file remain open, those objects will remain @@ -462,10 +520,26 @@ facilitate moving easily between them. (including writable) until it is explicitely closed. The file will be automatically closed once all objects in the file have been closed. +

    + Be warned, hoever, that there are circumstances where it is + not possible to delay closing a file. + For example, an MPI-IO file close is a collective call; all of + the processes that opened the file must close it collectively. + The file cannot be closed at some time in the future by each + process in an independent fashion. + Another example is that an application using an AFS token-based + file access privilage may destroy its AFS token after + H5Fclose has returned successfully. + This would make any future access to the file, or any object + within it, illegal. +

    + In such situations, applications must close all open objects + in a file before calling H5Fclose. + It is generally recommended to do so in all cases.

    Parameters:
    hid_t file_id -
    Identifier of a file to terminate access to. +
    IN: Identifier of a file to terminate access to.
    Returns:
    Returns a non-negative value if successful; @@ -502,16 +576,16 @@ facilitate moving easily between them.
    Parameters:
    hid_t loc_id -
    The identifier for of file or group in +
    IN: Identifier for of file or group in which name is defined.
    const char *name -
    The name of the group onto which the +
    IN: Name of the group onto which the file specified by child_id is to be mounted.
    hid_t child_id -
    The identifier of the file to be mounted. +
    IN: Identifier of the file to be mounted.
    hid_t plist_id -
    The identifier of the property list to be used. +
    IN: Identifier of the property list to be used.
    Returns:
    Returns a non-negative value if successful; @@ -554,10 +628,10 @@ facilitate moving easily between them.
    Parameters:
    hid_t loc_id -
    The file or group identifier for the location at which +
    IN: File or group identifier for the location at which the specified file is to be unmounted.
    const char *name -
    The name of the mount point. +
    IN: Name of the mount point.
    Returns:
    Returns a non-negative value if successful; @@ -597,11 +671,11 @@ facilitate moving easily between them. H5Freopen (file_id) to reopen it.

    The new file identifier should be closed by calling - H5Fclose() when it is no longer needed. + H5Fclose when it is no longer needed.

    Parameters:
    hid_t file_id -
    Identifier of a file for which an additional identifier +
    IN: Identifier of a file for which an additional identifier is required.
    Returns: @@ -658,7 +732,7 @@ H5F   HDF Help Desk
    -Last modified: 12 October 2000 +Last modified: 5 December 2001
    Describes HDF5 Release 1.5, Unreleased Development Branch -- cgit v0.12