Open or create a file

ss_file_open is a function defined in ssfile.c.

Synopsis:

ss_file_t * ss_file_open(ss_file_t *file, const char *name, unsigned flags, ss_prop_t *props)

Formal Arguments:

  • file: Optional handle to a persistent file object from a File table.
  • name: Optional name of file to be opened.
  • flags: HDF5-style file access flags.
  • props: Optional file property list (see *File Properties*).

Description: Explititly opens an SSlib file and returns a link to the ss_file_t object for that file. Either file or name or both may be specified. If one or the other (but not both) is specified then the file is simply opened with the name contained in the file object or the specified name. If both are specified then a mapping from the file object to the specified name is established, which is necessary if the name originally recorded in the Files table is no longer valid due to the file being moved in the file system.

Depending on flags, the file might be created if it doesn’t exist (H5_ACC_CREATE) or truncated if it does exist (H5_ACC_TRUNC). If the file is truncated, files which were mentioned in its File table are not automatically deleted or truncated and other files which link to this truncated file will subsequently contain dangling or invalid links.

SSlib supports transient objects by placing them in transient files. A transient file is simply a special SSlib file that doesn’t correspond to any underlying storage (not even an HDF5 file using the core virtual file driver). Such files support more or less the same SSlib operations as real files although some operations may be tuned for this special case (e.g., ss_file_flush). Transient files are always created for read and write access as are the scopes they contain, and are denoted as such by the the bit H5F_ACC_TRANSIENT in the flags argument. They share the same name space as their permanent cousins, and thus it is not possible to have a transient and permanent file both named “foo.saf” although creating a transient file doesn’t affect any file that might already exist by that name.

All File tables of the file that is newly opened are scanned and all of their members are added to the GFile array. If that array already had the name marked as open then the corresponding entry of the File table will be implicitly opened. Files opened implicitly need not be closed and can be opened explicitly at any time (although if one is going to open it explicitly it’s best to do so early on).

The ss_file_create function is a convenience for creating a new file.

Return Value: Returns a link to the ss_file_t object for the newly opened file on success; null on failure. If the file argument is supplied then this will be the successful return value.

Parallel Notes: Collective across the file’s communicator as specified by props.comm, defaulting to the same thing as the library’s communicator.

Issues: HDF5 doesn’t yet (1.6.0) support the H5F_ACC_TRANSIENT bit, which would essentially make all operations on the file no-ops. Therefore this functionality must be supported in SSlib.

See Also: