#include "base/cs_defs.h"

Include dependency graph for cs_file.h:

Typedefs
typedef struct _cs_file_t	cs_file_t
typedef long	cs_file_off_t

Functions
cs_file_t *	cs_file_open (const char *name, cs_file_mode_t mode, cs_file_access_t method)
	Create a file descriptor and open the associated file.
cs_file_t *	cs_file_open_default (const char *name, cs_file_mode_t mode)
	Create a file descriptor and open the associated file, using the default file communicator and access method.
cs_file_t *	cs_file_open_serial (const char *name, cs_file_mode_t mode)
	Create a file descriptor and open the associated file, using the serial IO on the root rank.
cs_file_t *	cs_file_free (cs_file_t *f)
	Destroy a file descriptor and close the associated file.
void	cs_file_in_memory_transfer_data (cs_file_t f, size_t nb, void data)
	Transfer a block of data to file in memory.
const char *	cs_file_get_name (const cs_file_t *f)
	Return a file's name.
void *	cs_file_in_memory_get_data (cs_file_t *f)
	Get pointer to data for file in memory.
void	cs_file_set_allow_read_global_eof (cs_file_t *f, bool allow_eof)
void	cs_file_set_big_endian (cs_file_t *f)
	Ensure that data is read or written in big-endian (network standard) format.
int	cs_file_get_swap_endian (const cs_file_t *f)
	Return a file's byte-swapping behavior.
void	cs_file_set_swap_endian (cs_file_t *f, int swap)
	Set a file's byte-swapping behavior.
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.
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.
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.
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.
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.
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.
cs_file_off_t	cs_file_tell (cs_file_t *f)
	Return the position of the file pointer.
char *	cs_file_gets (char s, const int size, const cs_file_t f, int *line)
	Formatted input from a text file (as fgets()).
char *	cs_file_gets_try (char s, const int size, const cs_file_t f, int *line)
	Formatted input from a text file if possible (as fgets()).
void	cs_file_dump (const cs_file_t *f)
	Dump the metadata of a file structure in human readable form.
void	cs_file_free_defaults (void)
	Free the default options for file access.
void	cs_file_get_default_access (cs_file_mode_t mode, cs_file_access_t *method)
	Get the default options for file access.
void	cs_file_set_default_access (cs_file_mode_t mode, cs_file_access_t method)
	Set the default options for file access.
cs_file_mpi_positioning_t	cs_file_get_mpi_io_positioning (void)
	Get the positioning method for MPI-IO.
void	cs_file_set_mpi_io_positioning (cs_file_mpi_positioning_t positioning)
	Set the positioning method for MPI-IO.
void	cs_file_defaults_info (void)
	Print information on default options for file access.
int	cs_file_mkdir_default (const char *path)
	Create a new directory using default permissions.
int	cs_file_isreg (const char *path)
	Check if a file exists and is a regular file.
int	cs_file_isdir (const char *path)
	Check if a directory exists.
char **	cs_file_listdir (const char *path)
	List files inside a directory.
cs_file_off_t	cs_file_size (const char *path)
	Return the size of a file.
int	cs_file_remove (const char *path)
	Remove a file if it exists and is a regular file or an empty directory.
int	cs_file_endswith (const char path, const char end)
	Check if file name/path ends with a specific string.

Variables
const char *	cs_file_access_name []
const char *	cs_file_mpi_positioning_name []

Typedef Documentation

◆ cs_file_off_t

typedef long cs_file_off_t

Offset for file position indicator

◆ cs_file_t

typedef struct _cs_file_t cs_file_t

File descriptor (opaque object)

Enumeration Type Documentation

◆ cs_file_access_t

enum cs_file_access_t

Enumerator
CS_FILE_DEFAULT	Default IO option
CS_FILE_STDIO_SERIAL	Serial standard C IO (funnelled through rank 0 in parallel)
CS_FILE_STDIO_PARALLEL	Per-process standard C IO (for reading only)
CS_FILE_MPI_INDEPENDENT	Non-collective MPI-IO with independent file open and close (for reading only)
CS_FILE_MPI_NON_COLLECTIVE	Non-collective MPI-IO with collective file open and close
CS_FILE_MPI_COLLECTIVE	Collective MPI-IO
CS_FILE_IN_MEMORY_SERIAL	Buffer in rank 0 memory (serialized in parallel)

◆ cs_file_mode_t

enum cs_file_mode_t

Enumerator
CS_FILE_MODE_READ	Read mode
CS_FILE_MODE_WRITE	Write mode
CS_FILE_MODE_APPEND	Append

◆ cs_file_mpi_positioning_t

enum cs_file_mpi_positioning_t

Enumerator
CS_FILE_MPI_EXPLICIT_OFFSETS	Use explicit offsets positioning with MPI-IO
CS_FILE_MPI_INDIVIDUAL_POINTERS	Use individual file pointer positioning with MPI-IO

◆ cs_file_seek_t

enum cs_file_seek_t

Enumerator
CS_FILE_SEEK_SET	Seek from beginning of file
CS_FILE_SEEK_CUR	Seek from current position
CS_FILE_SEEK_END	Seek from end of file

Function Documentation

◆ cs_file_defaults_info()

void cs_file_defaults_info ( void )

Print information on default options for file access.

◆ cs_file_dump()

void cs_file_dump ( const cs_file_t * f )

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

Parameters

[in] f cs_file_t descriptor

◆ cs_file_endswith()

int cs_file_endswith	(	const char *	path,
		const char *	end )

Check if file name/path ends with a specific string.

The function returns an int: 1 if the file name ends with the given string, 0 otherwise.

Parameters

[in]	path	name of file
[in]	end	end string to test

Returns: 1 if the path ends with the given string, 0 otherwise.

◆ cs_file_free()

cs_file_t * cs_file_free ( cs_file_t * f )

Destroy a file descriptor and close the associated file.

Parameters

[in,out] f file descriptor to destroy

◆ cs_file_free_defaults()

void cs_file_free_defaults ( void )

Free the default options for file access.

◆ cs_file_get_default_access()

void cs_file_get_default_access	(	cs_file_mode_t	mode,
		cs_file_access_t *	method )

Get the default options for file access.

Parameters

[in]	mode	file mode for which the default is queried (write and append use the same method, and are interchangeable here)
[out]	method	default file access method, or nullptr

◆ cs_file_get_mpi_io_positioning()

cs_file_mpi_positioning_t cs_file_get_mpi_io_positioning ( void )

Get the positioning method for MPI-IO.

For details, see cs_file_set_mpi_io_positioning.

Returns: positioning method for MPI-IO

◆ cs_file_get_name()

const char * cs_file_get_name ( const cs_file_t * f )

Return a file's name.

Parameters

[in] f cs_file_t descriptor

Returns: pointer to the file's name.

◆ cs_file_get_swap_endian()

int cs_file_get_swap_endian ( const cs_file_t * f )

Return a file's byte-swapping behavior.

Parameters

[in] f cs_file_t descriptor

Returns: 0 if file's endianness is the same as the system's, 1 otherwise.

◆ cs_file_gets()

char * cs_file_gets	(	char *	s,
		const int	size,
		const cs_file_t *	f,
		int *	line )

Formatted input from a text file (as fgets()).

Parameters

[out]	s	buffer to which string is to be read.
[in]	size	maximum number of characters to be read plus one.
[in]	f	ecs_file_t descriptor.
[in,out]	line	file line number if available, or null.

Returns: s on success, null on error or when end of file occurs and no characters have been read.

Parameters

[out]	s	buffer to which string is to be read.
[in]	size	maximum number of characters to be read plus one.
[in]	f	ecs_file_t descriptor.
[in,out]	line	file line number if available, or nullptr.

Returns: s on success, nullptr on error or when end of file occurs and no characters have been read.

◆ cs_file_gets_try()

char * cs_file_gets_try	(	char *	s,
		const int	size,
		const cs_file_t *	f,
		int *	line )

Formatted input from a text file if possible (as fgets()).

This function is similar to cs_file_gets(), but failure to read a line due to an end-of-file condition is not considered an error with this variant, which may be used to read text files or sections thereof of unknown length.

Parameters

[out]	s	buffer to which string is to be read.
[in]	size	maximum number of characters to be read plus one.
[in]	f	cs_file_t descriptor.
[in,out]	line	file line number if available, or null.

Returns: s on success, null on error or when end of file occurs and no characters have been read.

This function is similar to cs_file_gets(), but failure to read a line due to an end-of-file condition is not considered an error with this variant, which may be used to read text files or sections thereof of unknown length.

Parameters

[out]	s	buffer to which string is to be read.
[in]	size	maximum number of characters to be read plus one.
[in]	f	cs_file_t descriptor.
[in,out]	line	file line number if available, or nullptr.

Returns: s on success, nullptr on error or when end of file occurs and no characters have been read.

◆ cs_file_in_memory_get_data()

void * cs_file_in_memory_get_data ( cs_file_t * f )

Get pointer to data for file in memory.

Parameters

[in] f cs_file_t descriptor

Returns: pointer to file data.

◆ cs_file_in_memory_transfer_data()

void cs_file_in_memory_transfer_data	(	cs_file_t *	f,
		size_t	nb,
		void *	data )

Transfer a block of data to file in memory.

Only for files opened using CS_FILE_IN_MEMORY_SERIAL.

Parameters

[in]	f	cs_file_t descriptor
[in]	nb	number of matching bytes for data
[in]	data	data buffer (ownership is relinquished by caller)

◆ cs_file_isdir()

int cs_file_isdir ( const char * path )

Check if a directory exists.

Parameters

[in] path directory path.

Returns: 1 if directory exists, 0 otherwise.

◆ cs_file_isreg()

int cs_file_isreg ( const char * path )

Check if a file exists and is a regular file.

Parameters

[in] path file path.

Returns: 1 if file exists and is a regular file, 0 otherwise.

◆ cs_file_listdir()

char ** cs_file_listdir ( const char * path )

List files inside a directory.

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

Parameters

[in] path name of directory.

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

◆ cs_file_mkdir_default()

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] path name 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.

◆ cs_file_open()

cs_file_t * cs_file_open	(	const char *	name,
		cs_file_mode_t	mode,
		cs_file_access_t	method )

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]	name	file name
[in]	mode	file access mode: read, write, or append
[in]	method	file access method (currently only C standard-IO when built without MPI)
[in]	hints	associated hints for MPI-IO, or MPI_INFO_NULL
[in]	block_comm	handle to MPI communicator used for distributed file block access (may be a subset of comm if some ranks do not directly access distributed data blocks)
[in]	comm	handle to main MPI communicator

Returns: pointer to cs_file_t file descriptor (nullptr in case of failure); currently, errors are fatal.

◆ cs_file_open_default()

cs_file_t * cs_file_open_default	(	const char *	name,
		cs_file_mode_t	mode )

Create a file descriptor and open the associated file, using the default file communicator and access method.

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

Parameters

[in]	name	file name
[in]	mode	file access mode: read, write, or append

Returns: pointer to cs_file_t file descriptor (nullptr in case of failure); currently, errors are fatal.

◆ cs_file_open_serial()

cs_file_t * cs_file_open_serial	(	const char *	name,
		cs_file_mode_t	mode )

Create a file descriptor and open the associated file, using the serial IO on the root rank.

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

Parameters

[in]	name	file name
[in]	mode	file access mode: read, write, or append

Returns: pointer to cs_file_t file descriptor (NULL in case of failure); currently, errors are fatal.

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

Parameters

[in]	name	file name
[in]	mode	file access mode: read, write, or append

Returns: pointer to cs_file_t file descriptor (nullptr in case of failure); currently, errors are fatal.

◆ cs_file_read_block()

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]	f	cs_file_t descriptor
[out]	buf	pointer to location receiving data
[in]	size	size of each item of data in bytes
[in]	stride	number of (interlaced) values per block item
[in]	global_num_start	global number of first block item (1 to n numbering)
[in]	global_num_end	global 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.

◆ cs_file_read_global()

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]	f	cs_file_t descriptor
[out]	buf	pointer to location receiving data
[in]	size	size of each item of data in bytes
[in]	ni	number of items to read

Returns: the number of items (not bytes) sucessfully read; currently, errors are fatal.

◆ cs_file_remove()

int cs_file_remove ( const char * path )

Remove a file if it exists and is a regular file or an empty directory.

Parameters

[in] path file path.

Returns: 0 in case of success or if file does not exist, not 0 otherwise.

◆ cs_file_seek()

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]	f	cs_file_t descriptor
[in]	offset	add to position specified to whence to obtain new position, measured in characters from the beginning of the file
[in]	whence	beginning 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.

◆ cs_file_set_allow_read_global_eof()

void cs_file_set_allow_read_global_eof	(	cs_file_t *	f,
		bool	allow_eof )

◆ cs_file_set_big_endian()

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] f cs_file_t descriptor

◆ cs_file_set_default_access()

void cs_file_set_default_access	(	cs_file_mode_t	mode,
		cs_file_access_t	method )

Set the default options for file access.

If the method given contains incompatible values, such as when setting MPI-IO methods when MPI-IO is not available, a "reasonable" default is used instead.

Parameters

[in]	mode	file mode for which the default is being set (write and append use the same method, and are interchangeable here)
[in]	method	default access method to set

◆ cs_file_set_mpi_io_positioning()

void cs_file_set_mpi_io_positioning ( cs_file_mpi_positioning_t positioning )

Set the positioning method for MPI-IO.

It is not always known whether a performance or robustness difference is to be expected using explicit file offsets or individual file pointers. Perusal of a sampling of ROMIO code would seem to indicate that no difference is to be expected, but this might change with MPI IO variants or file systems, so this advanced setting is made possible.

This setting is not available on a per-file basis, though this could be done in the future in the unexpected case of performance results showing this would be useful.

Parameters

[in] positioning chosen positioning method for MPI-IO

◆ cs_file_set_swap_endian()

void cs_file_set_swap_endian	(	cs_file_t *	f,
		int	swap )

Set a file's byte-swapping behavior.

Parameters

[in,out]	f	cs_file_t descriptor
[in]	swap	1 if bytes must be swapped, 0 otherwise

◆ cs_file_size()

cs_file_off_t cs_file_size ( const char * path )

Return the size of a file.

If the file does not exist, 0 is returned.

Note also that for some special files, such as files in the Linux /proc directory, this may return 0.

Parameters

[in] path file path.

Returns: size of file.

◆ cs_file_tell()

cs_file_off_t cs_file_tell ( cs_file_t * f )

Return the position of the file pointer.

In parallel, we consider the file pointer to be equal to the highest value of the individual file pointers.

Parameters

[in] f cs_file_t descriptor

Returns: current position of the file pointer.

◆ cs_file_write_block()

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]	f	cs_file_t descriptor
[in]	buf	pointer to location containing data
[in]	size	size of each item of data in bytes
[in]	stride	number of (interlaced) values per block item
[in]	global_num_start	global number of first block item (1 to n numbering)
[in]	global_num_end	global 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.

◆ cs_file_write_block_buffer()

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]	f	cs_file_t descriptor
[in,out]	buf	pointer to location containing data
[in]	size	size of each item of data in bytes
[in]	stride	number of (interlaced) values per block item
[in]	global_num_start	global number of first block item (1 to n numbering)
[in]	global_num_end	global 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.

◆ cs_file_write_global()

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]	f	cs_file_t descriptor
[in]	buf	pointer to location containing data
[in]	size	size of each item of data in bytes
[in]	ni	number of items to write

Returns: the number of items (not bytes) sucessfully written; currently, errors are fatal.

Variable Documentation

◆ cs_file_access_name

const char* cs_file_access_name[]

extern

◆ cs_file_mpi_positioning_name

const char* cs_file_mpi_positioning_name[]

extern

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 }
enum	cs_file_access_t { CS_FILE_DEFAULT , CS_FILE_STDIO_SERIAL , CS_FILE_STDIO_PARALLEL , CS_FILE_MPI_INDEPENDENT , CS_FILE_MPI_NON_COLLECTIVE , CS_FILE_MPI_COLLECTIVE , CS_FILE_IN_MEMORY_SERIAL }
enum	cs_file_mpi_positioning_t { CS_FILE_MPI_EXPLICIT_OFFSETS , CS_FILE_MPI_INDIVIDUAL_POINTERS }

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ cs_file_off_t

◆ cs_file_t

Enumeration Type Documentation

◆ cs_file_access_t

◆ cs_file_mode_t

◆ cs_file_mpi_positioning_t

◆ cs_file_seek_t

Function Documentation

◆ cs_file_defaults_info()

◆ cs_file_dump()

◆ cs_file_endswith()

◆ cs_file_free()

◆ cs_file_free_defaults()

◆ cs_file_get_default_access()

◆ cs_file_get_mpi_io_positioning()

◆ cs_file_get_name()

◆ cs_file_get_swap_endian()

◆ cs_file_gets()

◆ cs_file_gets_try()

◆ cs_file_in_memory_get_data()

◆ cs_file_in_memory_transfer_data()

◆ cs_file_isdir()

◆ cs_file_isreg()

◆ cs_file_listdir()

◆ cs_file_mkdir_default()

◆ cs_file_open()

◆ cs_file_open_default()

◆ cs_file_open_serial()

◆ cs_file_read_block()

◆ cs_file_read_global()

◆ cs_file_remove()

◆ cs_file_seek()

◆ cs_file_set_allow_read_global_eof()

◆ cs_file_set_big_endian()

◆ cs_file_set_default_access()

◆ cs_file_set_mpi_io_positioning()

◆ cs_file_set_swap_endian()

◆ cs_file_size()

◆ cs_file_tell()

◆ cs_file_write_block()

◆ cs_file_write_block_buffer()

◆ cs_file_write_global()

Variable Documentation

◆ cs_file_access_name

◆ cs_file_mpi_positioning_name