Code_Saturne
CFD tool
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Macros | Typedefs | Enumerations | Functions
cs_file.h File Reference
#include "cs_defs.h"
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define CS_FILE_NO_MPI_IO   (1 << 0)
 
#define CS_FILE_NO_PREDISTRIBUTE   (1 << 1)
 
#define CS_FILE_EXPLICIT_OFFSETS   (1 << 2)
 
#define CS_FILE_INDIVIDUAL_POINTERS   (1 << 3)
 

Typedefs

typedef struct _cs_file_t cs_file_t
 
typedef unsigned int cs_file_hints_t
 
typedef long cs_file_off_t
 

Enumerations

enum  cs_file_mode_t { CS_FILE_MODE_READ, CS_FILE_MODE_WRITE, CS_FILE_MODE_APPEND }
 
enum  cs_file_seek_t { CS_FILE_SEEK_SET, CS_FILE_SEEK_CUR, CS_FILE_SEEK_END }
 

Functions

cs_file_tcs_file_open (const char *name, cs_file_mode_t mode, cs_file_hints_t hints)
 Create a file descriptor and open the associated file. More...
 
cs_file_tcs_file_free (cs_file_t *f)
 Destroy a file descriptor and close the associated file. More...
 
const char * cs_file_get_name (const cs_file_t *f)
 Return a file's name. More...
 
void cs_file_set_big_endian (cs_file_t *f)
 Ensure that data is read or written in big-endian (network standard) format. More...
 
int cs_file_get_swap_endian (const cs_file_t *f)
 Return a file's byte-swapping behavior. More...
 
void cs_file_set_swap_endian (cs_file_t *f, int swap)
 Set a file's byte-swapping behavior. More...
 
size_t cs_file_read_global (cs_file_t *f, void *buf, size_t size, size_t ni)
 Read global data from a file, distributing it to all processes associated with that file. More...
 
size_t cs_file_write_global (cs_file_t *f, const void *buf, size_t size, size_t ni)
 Write global data to a file. More...
 
size_t cs_file_read_block (cs_file_t *f, void *buf, size_t size, size_t stride, cs_gnum_t global_num_start, cs_gnum_t global_num_end)
 Read data to a buffer, distributing a contiguous part of it to each process associated with a file. More...
 
size_t cs_file_write_block (cs_file_t *f, const void *buf, size_t size, size_t stride, cs_gnum_t global_num_start, cs_gnum_t global_num_end)
 Write data to a file, each associated process providing a contiguous part of this data. More...
 
size_t cs_file_write_block_buffer (cs_file_t *f, void *buf, size_t size, size_t stride, cs_gnum_t global_num_start, cs_gnum_t global_num_end)
 Write data to a file, each associated process providing a contiguous part of this data. More...
 
int cs_file_seek (cs_file_t *f, cs_file_off_t offset, cs_file_seek_t whence)
 Update the file pointer according to whence. More...
 
cs_file_off_t cs_file_tell (cs_file_t *f)
 Return the position of the file pointer. More...
 
cs_file_hints_t cs_file_get_default_semantics (void)
 Get the default semantics for file access. More...
 
int cs_file_set_default_semantics (cs_file_hints_t hints)
 Set the default semantics for file access. More...
 
void cs_file_dump (const cs_file_t *f)
 Dump the metadata of a file structure in human readable form. More...
 
int cs_file_mkdir_default (const char *path)
 Create a new directory using default permissions. More...
 
int cs_file_isreg (const char *path)
 Check if a file exists and is a regular file. More...
 
int cs_file_isdir (const char *path)
 Check if a directory exists. More...
 
char ** cs_file_listdir (const char *path)
 List files inside a directory. More...
 

Macro Definition Documentation

#define CS_FILE_EXPLICIT_OFFSETS   (1 << 2)
#define CS_FILE_INDIVIDUAL_POINTERS   (1 << 3)
#define CS_FILE_NO_MPI_IO   (1 << 0)
#define CS_FILE_NO_PREDISTRIBUTE   (1 << 1)

Typedef Documentation

typedef unsigned int cs_file_hints_t
typedef long cs_file_off_t
typedef struct _cs_file_t cs_file_t

Enumeration Type Documentation

Enumerator
CS_FILE_MODE_READ 
CS_FILE_MODE_WRITE 
CS_FILE_MODE_APPEND 
Enumerator
CS_FILE_SEEK_SET 
CS_FILE_SEEK_CUR 
CS_FILE_SEEK_END 

Function Documentation

void cs_file_dump ( const cs_file_t f)

Dump the metadata of a file structure in human readable form.

Parameters
[in]fcs_file_t descriptor

Here is the call graph for this function:

cs_file_t* cs_file_free ( cs_file_t f)

Destroy a file descriptor and close the associated file.

Parameters
[in,out]ffile descriptor to destroy
cs_file_hints_t cs_file_get_default_semantics ( void  )

Get the default semantics for file access.

Returns
current default semantics for file access.
const char* cs_file_get_name ( const cs_file_t f)

Return a file's name.

Parameters
[in]fcs_file_t descriptor
Returns
pointer to the file's name.
int cs_file_get_swap_endian ( const cs_file_t f)

Return a file's byte-swapping behavior.

Parameters
[in]fcs_file_t descriptor
Returns
0 if file's endianness is the same as the system's, 1 otherwise.
int cs_file_isdir ( const char *  path)

Check if a directory exists.

Parameters
[in]pathdirectory path.
Returns
1 if directory exists, 0 otherwise.

Here is the call graph for this function:

int cs_file_isreg ( const char *  path)

Check if a file exists and is a regular file.

Parameters
[in]pathfile path.
Returns
1 if file exists and is a regular file, 0 otherwise.

Here is the call graph for this function:

char** cs_file_listdir ( const char *  path)

List files inside a directory.

The array returned must be freed by the caller using BFT_FREE, as well as the individual entries in the array.

Parameters
[in]pathname of directory.
Returns
an array of file names in a directory. The last entry is set to NULL. If no means to list the directory or an error occured, the return value is simply NULL.

Here is the call graph for this function:

int cs_file_mkdir_default ( const char *  path)

Create a new directory using default permissions.

This function is similar to the POSIX function mkdir(), except that it has no "mode" argument: by default, on a POSIX type system, permissions include read, write, and execute access for the user, group and others, modified by the users umask value (so with a typical configuration, the user will have read, write, and execute pemission, the group and others will only have read and execute permission, but this behavior may be modified).

Also, contrary to the usual mkdir(), if the directory already exists (and is truly a directory), this is considered a success and not a failure, and 0 is returned: the aim of this function is to make a directory available, so if it already exists, this is considered acceptable.

Parameters
[in]pathname of new directory.
Returns
0 on success, -1 if an error occured (in which case errno contains the appropriate error code). If the underlying system has no mkdir() function or it was not detected upon BFT configuration, 1 is returned.

Here is the call graph for this function:

cs_file_t* cs_file_open ( const char *  name,
cs_file_mode_t  mode,
cs_file_hints_t  hints 
)

Create a file descriptor and open the associated file.

By default, data is written or read as native data. This behavior may be modified by cs_file_set_swap_endian().

Parameters
[in]namefile name
[in]modefile acces mode: read, write, or append
[in]hintsfile I/O hints (for MPI and MPI I/O behavior)
Returns
pointer to cs_file_t file descriptor (NULL in case of failure); currently, errors are fatal.

Here is the call graph for this function:

size_t cs_file_read_block ( cs_file_t f,
void *  buf,
size_t  size,
size_t  stride,
cs_gnum_t  global_num_start,
cs_gnum_t  global_num_end 
)

Read data to a buffer, distributing a contiguous part of it to each process associated with a file.

Each process should receive a (possibly empty) block of the data, and we should have: global_num_start at rank 0 = 1 global_num_start at rank i+1 = global_num_end at rank i. Otherwise, behavior (especially positioning for future reads) is undefined.

Parameters
[in]fcs_file_t descriptor
[out]bufpointer to location receiving data
[in]sizesize of each item of data in bytes
[in]stridenumber of (interlaced) values per block item
[in]global_num_startglobal number of first block item (1 to n numbering)
[in]global_num_endglobal number of past-the end block item (1 to n numbering)
Returns
the (local) number of items (not bytes) sucessfully read; currently, errors are fatal.
size_t cs_file_read_global ( cs_file_t f,
void *  buf,
size_t  size,
size_t  ni 
)

Read global data from a file, distributing it to all processes associated with that file.

Parameters
[in]fcs_file_t descriptor
[out]bufpointer to location receiving data
[in]sizesize of each item of data in bytes
[in]ninumber of items to read
Returns
the number of items (not bytes) sucessfully read; currently, errors are fatal.
int cs_file_seek ( cs_file_t f,
cs_file_off_t  offset,
cs_file_seek_t  whence 
)

Update the file pointer according to whence.

Parameters
[in,out]fcs_file_t descriptor
[in]offsetadd to position specified to whence to obtain new position, measured in characters from the beginning of the file
[in]whencebeginning if CS_FILE_SEEK_SET, current if CS_FILE_SEEK_CUR, or end-of-file if CS_FILE_SEEK_END
Returns
0 upon success, nonzero otherwise; currently, errors are fatal.
void cs_file_set_big_endian ( cs_file_t f)

Ensure that data is read or written in big-endian (network standard) format.

Parameters
[in,out]fcs_file_t descriptor
int cs_file_set_default_semantics ( cs_file_hints_t  hints)

Set the default semantics for file access.

This may fail if semantics given contain incompatible values, such as (CS_FILE_EXPLICIT_OFFSETS | CS_FILE_INDIVIDUAL_POINTERS), or when setting MPI-IO access semantics when MPI-IO is not available.

Parameters
[in]hintsflag (bit mask) defining default semantics
Returns
0 if the semantics were valid, 1 otherwise.
void cs_file_set_swap_endian ( cs_file_t f,
int  swap 
)

Set a file's byte-swapping behavior.

Parameters
[in,out]fcs_file_t descriptor
[in]swap1 if bytes must be swapped, 0 otherwise
cs_file_off_t cs_file_tell ( cs_file_t f)

Return the position of the file pointer.

When using MPI-IO with individual file pointers, we consider the file pointer to be equal to the highest value of the individual file pointers.

Parameters
[in]fcs_file_t descriptor
Returns
current position of the file pointer.
size_t cs_file_write_block ( cs_file_t f,
const void *  buf,
size_t  size,
size_t  stride,
cs_gnum_t  global_num_start,
cs_gnum_t  global_num_end 
)

Write data to a file, each associated process providing a contiguous part of this data.

Each process should provide a (possibly empty) block of the data, and we should have: global_num_start at rank 0 = 1 global_num_start at rank i+1 = global_num_end at rank i. Otherwise, behavior (especially positioning for future reads) is undefined.

This function may require an internal copy of the data to ensure that the buffer contents are not modified, so if the buffer contents are temporary values, to be deleted after writing, using cs_file_write_block_buffer() instead may be used to avoid an unneeded memory allocation and copy.

Parameters
[in]fcs_file_t descriptor
[in]bufpointer to location containing data
[in]sizesize of each item of data in bytes
[in]stridenumber of (interlaced) values per block item
[in]global_num_startglobal number of first block item (1 to n numbering)
[in]global_num_endglobal number of past-the end block item (1 to n numbering)
Returns
the (local) number of items (not bytes) sucessfully written; currently, errors are fatal.

Here is the call graph for this function:

size_t cs_file_write_block_buffer ( cs_file_t f,
void *  buf,
size_t  size,
size_t  stride,
cs_gnum_t  global_num_start,
cs_gnum_t  global_num_end 
)

Write data to a file, each associated process providing a contiguous part of this data.

Each process should provide a (possibly empty) block of the data, and we should have: global_num_start at rank 0 = 1 global_num_start at rank i+1 = global_num_end at rank i. Otherwise, behavior (especially positioning for future reads) is undefined.

This function is intended to be used mainly data that is already a copy of original data (such as data that has been redistributed across processors just for the sake of output), or that is to be deleted after writing, so it may modify the values in its input buffer (notably to convert from little-endian to big-endian of vice-versa if necessary).

Parameters
[in]fcs_file_t descriptor
[in,out]bufpointer to location containing data
[in]sizesize of each item of data in bytes
[in]stridenumber of (interlaced) values per block item
[in]global_num_startglobal number of first block item (1 to n numbering)
[in]global_num_endglobal number of past-the end block item (1 to n numbering)
Returns
the (local) number of items (not bytes) sucessfully written; currently, errors are fatal.
size_t cs_file_write_global ( cs_file_t f,
const void *  buf,
size_t  size,
size_t  ni 
)

Write global data to a file.

Under MPI, data is only written by the associated communicator's root rank. The buffers on other ranks are ignored, though the file offset is updated (i.e. the call to this function is collective).

Parameters
[in]fcs_file_t descriptor
[in]bufpointer to location containing data
[in]sizesize of each item of data in bytes
[in]ninumber of items to write
Returns
the number of items (not bytes) sucessfully written; currently, errors are fatal.