Code_Saturne
CFD tool
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Functions
ecs_file.c File Reference
#include "cs_config.h"
#include <assert.h>
#include <errno.h>
#include <stdio.h>
#include <stdarg.h>
#include <string.h>
#include <zlib.h>
#include <sys/stat.h>
#include <sys/types.h>
#include "ecs_def.h"
#include "ecs_file.h"
#include "ecs_mem.h"

Functions

int ecs_file_printf (const ecs_file_t *const f, const char *const format,...)
 Formatted output to a text file (as fprintf()). More...
 
ecs_file_tecs_file_open (const char *name, const ecs_file_mode_t mode, const ecs_file_type_t type)
 Create a `ecs_file_t' file descriptor and open the associated file. More...
 
ecs_file_tecs_file_free (ecs_file_t *f)
 Destroy a `ecs_file_t' descriptor and close the associated file. More...
 
ecs_file_tecs_file_free_descriptor (ecs_file_t *f)
 
int ecs_file_open_stream (ecs_file_t *f, ecs_file_mode_t mode)
 Open `ecs_file_t' descriptor's associated file. More...
 
int ecs_file_close_stream (ecs_file_t *f)
 Close a ecs_file_t file descriptor's associated file. More...
 
int ecs_file_eof (const ecs_file_t *f)
 Test the end-of-file indicator for a given file. More...
 
int ecs_file_flush (ecs_file_t *f)
 Force write of all user-space buffered data for a given file. More...
 
ecs_file_off_t ecs_file_tell (ecs_file_t *f)
 Obtain the current value of a file's position indicator. More...
 
void ecs_file_rewind (ecs_file_t *f)
 Sets the file position indicator to the beginning of the file. More...
 
int ecs_file_seek (ecs_file_t *f, const ecs_file_off_t offset, const ecs_file_seek_t whence)
 Sets a file's position indicator. More...
 
const char * ecs_file_get_name (const ecs_file_t *f)
 Return a file's name. More...
 
ecs_file_type_t ecs_file_get_type (const ecs_file_t *f)
 Return a file's type. More...
 
void ecs_file_set_type (ecs_file_t *f, const ecs_file_type_t type)
 Change a file's type. More...
 
void ecs_file_set_big_endian (ecs_file_t *f)
 Ensure that data is read or written in big-endian (network standard) format. More...
 
int ecs_file_get_swap_endian (const ecs_file_t *f)
 Return a file's byte-swapping behavior. More...
 
void ecs_file_set_swap_endian (ecs_file_t *f, const int swap)
 Set a file's byte-swapping behavior. More...
 
int ecs_file_read_check_error (const ecs_file_t *f, const int line)
 Test a file's error or EOF condition. More...
 
char * ecs_file_gets (char *s, const int size, const ecs_file_t *f, int *line)
 Formatted input from a text file (as fgets()). More...
 
char * ecs_file_gets_try (char *s, const int size, const ecs_file_t *f, int *line)
 Formatted input from a text file if possible (as fgets()). More...
 
size_t ecs_file_read (void *rec, const size_t size, const size_t ni, const ecs_file_t *f)
 Read a binary C or Fortran type record. More...
 
size_t ecs_file_read_try (void *rec, const size_t size, const size_t ni, const ecs_file_t *f)
 Read a binary C or Fortran type record. More...
 
size_t ecs_file_write (const void *rec, const size_t size, const size_t ni, const ecs_file_t *f)
 Write a binary C or Fortran type record. More...
 
void ecs_file_swap_endian (void *dest, const void *src, const size_t size, const size_t ni)
 Convert data from "little-endian" to "big-endian" or the reverse. More...
 
int ecs_file_mkdir_default (const char *pathname)
 Create a new directory using default permissions. More...
 
int ecs_file_isreg (const char *name)
 Check if a file exists and is a regular file. More...
 
int ecs_file_isdir (const char *name)
 Check if a directory exists. More...
 
const char * ecs_file_version_zlib (void)
 Indicate Zlib version available at run time. More...
 
const char * ecs_file_version_build_zlib (void)
 Indicate Zlib version available at compilation time. More...
 

Function Documentation

int ecs_file_close_stream ( ecs_file_t f)

Close a ecs_file_t file descriptor's associated file.

If the file is already closed, this function does nothing.

Parameters
[in]fecs_file_t descriptor.
Returns
0 in case of success, system error code in case of failure (or Zlib error code in case of a Zlib specific error for a gzipped file).

Here is the call graph for this function:

int ecs_file_eof ( const ecs_file_t f)

Test the end-of-file indicator for a given file.

Parameters
[in]fecs_file_t descriptor.
Returns
0 if the end-of-file has not been reached, or non-zero (1 or feof() return value) otherwise.
int ecs_file_flush ( ecs_file_t f)

Force write of all user-space buffered data for a given file.

Parameters
[in]fecs_file_t descriptor.
Returns
0 upon successful completion, system error code otherwise.

Here is the call graph for this function:

ecs_file_t* ecs_file_free ( ecs_file_t f)

Destroy a `ecs_file_t' descriptor and close the associated file.

The descriptor may only be destroyed if the file was successfully closed. To force destruction of a ecs_file_t descriptor even if the associated file was not closed, use (ecs_file_free_force()).

The associated file is only closed if this was not already the case.

Parameters
[in]fecs_file_t descriptor.
Returns
pointer to ecs_file_t file descriptor (NULL in case of, success, f in case of failure).

Here is the call graph for this function:

ecs_file_t* ecs_file_free_descriptor ( ecs_file_t f)
const char* ecs_file_get_name ( const ecs_file_t f)

Return a file's name.

Parameters
[in]fecs_file_t descriptor.
Returns
pointer to file's name.
int ecs_file_get_swap_endian ( const ecs_file_t f)

Return a file's byte-swapping behavior.

Parameters
[in]fecs_file_t descriptor.
Returns
0 if file's endianness is the same as the system's, 1 otherwise.
ecs_file_type_t ecs_file_get_type ( const ecs_file_t f)

Return a file's type.

Parameters
[in]fecs_file_t descriptor.
Returns
file's type.
char* ecs_file_gets ( char *  s,
const int  size,
const ecs_file_t f,
int *  line 
)

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

Parameters
[out]sbuffer to which string is to be read.
[in]sizemaximum number of characters to be read plus one.
[in]fecs_file_t descriptor.
[in,out]linefile 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.
char* ecs_file_gets_try ( char *  s,
const int  size,
const ecs_file_t f,
int *  line 
)

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

This function is similar to ecs_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]sbuffer to which string is to be read.
[in]sizemaximum number of characters to be read plus one.
[in]fecs_file_t descriptor.
[in,out]linefile 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.
int ecs_file_isdir ( const char *  name)

Check if a directory exists.

Parameters
[in]namedirectory name.
Returns
1 if directory exists, 0 otherwise.

Here is the call graph for this function:

int ecs_file_isreg ( const char *  name)

Check if a file exists and is a regular file.

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

Here is the call graph for this function:

int ecs_file_mkdir_default ( const char *  pathname)

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]pathnamename 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 ECS configuration, 1 is returned.

Here is the call graph for this function:

ecs_file_t* ecs_file_open ( const char *  name,
const ecs_file_mode_t  mode,
const ecs_file_type_t  type 
)

Create a `ecs_file_t' file descriptor and open the associated file.

By default, data is written or read in native format (as regards big-endian or little-endian). This behavior may be modified by ecs_file_set_big_endian() or ecs_file_set_swap_endian().

Parameters
[in]namefile name.
[in]modefile acces mode: read, write, or append.
[in]typefile type: text, binary, or Fortran binary.
Returns
pointer to ecs_file_t file descriptor (NULL in case of failure).

Here is the call graph for this function:

int ecs_file_open_stream ( ecs_file_t f,
ecs_file_mode_t  mode 
)

Open `ecs_file_t' descriptor's associated file.

If the file is already open, this function does nothing.

Parameters
[in]fecs_file_t descriptor.
[in]modefile acces mode: read, write, or append.
Returns
0 in case of success, system error code in case of failure (or Zlib error code in case of Zlib memory allocation problem for a gzipped file).

Here is the call graph for this function:

int ecs_file_printf ( const ecs_file_t *const  f,
const char *const  format,
  ... 
)

Formatted output to a text file (as fprintf()).

Parameters
[in]fecs_file_t descriptor.
[in]formatformat string, as printf() and family.
[in]...variable arguments based on format string.
Returns
number of characters printed, not counting the trailing '\0' used to end output strings

Here is the call graph for this function:

size_t ecs_file_read ( void *  rec,
const size_t  size,
const size_t  ni,
const ecs_file_t f 
)

Read a binary C or Fortran type record.

A Fortran record compatible with most compilers is structured as follows:

  • a 4-byte integer indicating the number of bytes in the record.
  • the raw data
  • a 4-byte integer indicating the number of bytes in the record.

A C record contains only the raw data.

Parameters
[out]recpointer to location receiving data.
[in]sizesize of each item of data in bytes.
[in]ninumber of items to read.
[in]fecs_file_t descriptor.
Returns
the number of items (not bytes) sucessfully read; for a Fortran record, if the whole record could not be read, returns 0.
int ecs_file_read_check_error ( const ecs_file_t f,
const int  line 
)

Test a file's error or EOF condition.

Parameters
[in]fecs_file_t descriptor.
[in,out]linefile line number if available, or NULL.
Returns
0 if no error, system error code, or -1 if EOF.

Here is the call graph for this function:

size_t ecs_file_read_try ( void *  rec,
const size_t  size,
const size_t  ni,
const ecs_file_t f 
)

Read a binary C or Fortran type record.

This function is similar to ecs_file_read(), but failure to read a record due to an end-of-file condition is not considered an error with this variant, which may be used to read records whose presence in the file is unknown.

A Fortran record compatible with most compilers is structured as follows:

  • a 4-byte integer indicating the number of bytes in the record.
  • the raw data
  • a 4-byte integer indicating the number of bytes in the record.

A C record contains only the raw data.

Parameters
[out]recpointer to location receiving data.
[in]sizesize of each item of data in bytes.
[in]ninumber of items to read.
[in]fecs_file_t descriptor.
Returns
the number of items (not bytes) sucessfully read; for a Fortran record, if the whole record could not be read, returns 0.
void ecs_file_rewind ( ecs_file_t f)

Sets the file position indicator to the beginning of the file.

A successful call to this function clears the end-of-file indicator for this file.

Parameters
[in]fecs_file_t descriptor.

Here is the call graph for this function:

int ecs_file_seek ( ecs_file_t f,
const ecs_file_off_t  offset,
const ecs_file_seek_t  whence 
)

Sets a file's position indicator.

This function may call the libc's fseek() function, or Zlib's gzseek() function. The C 99 standard draft specifies that for a text file, the offset argument to fseek() should be zero or a value returned by an earlier successful call to ftell() (here ecs_file_ftell()) on a stream (here a ecs_file_t structure). Zlib's gzseek() does not support SEEK_END, at least as of version 1.2.1.

A successful call to this function clears the end-of-file indicator for this file.

Parameters
[in]fecs_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 ECS_FILE_SEEK_SET, current if ECS_FILE_SEEK_CUR, or end-of-file if ECS_FILE_SEEK_END.
Returns
0 upon success, nonzero otherwise.

Here is the call graph for this function:

void ecs_file_set_big_endian ( ecs_file_t f)

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

By default, data is written or read in native format (as regards big-endian or little-endian)..

Parameters
[in,out]fecs_file_t descriptor.
void ecs_file_set_swap_endian ( ecs_file_t f,
const int  swap 
)

Set a file's byte-swapping behavior.

Using this function assumes one is familiar with a file's coding or structure; use with caution.

Parameters
[in]fecs_file_t descriptor.
[in]swap1 if bytes must be swapped, 0 otherwise.
void ecs_file_set_type ( ecs_file_t f,
const ecs_file_type_t  type 
)

Change a file's type.

Using this function assumes one is familiar with a file's coding or structure; use with caution.

Parameters
[in,out]fecs_file_t descriptor.
[in]typetext, binary, or Fortran binary type descriptor.
void ecs_file_swap_endian ( void *  dest,
const void *  src,
const size_t  size,
const size_t  ni 
)

Convert data from "little-endian" to "big-endian" or the reverse.

The memory areas pointed to by src and dest should overlap either exactly or not at all.

Parameters
[out]destpointer to converted data location.
[in]srcpointer to source data location.
[in]sizesize of each item of data in bytes.
[in]ninumber of data items.
ecs_file_off_t ecs_file_tell ( ecs_file_t f)

Obtain the current value of a file's position indicator.

Parameters
[in]fecs_file_t descriptor.
Returns
current value of the file's position indicator, or -1 in case of failure.

Here is the call graph for this function:

const char* ecs_file_version_build_zlib ( void  )

Indicate Zlib version available at compilation time.

It may be useful to compare the Zlib version used at compile and link time in case we use dynamic libraries.

Returns
pointer to string indicating Zlib version at compilation, or NULL if Zlib support is not available.
const char* ecs_file_version_zlib ( void  )

Indicate Zlib version available at run time.

It may be useful to compare the Zlib version used at compile and run time in case we use dynamic libraries.

Returns
pointer to string indicating Zlib version in use, or NULL if Zlib support is not available.
size_t ecs_file_write ( const void *  rec,
const size_t  size,
const size_t  ni,
const ecs_file_t f 
)

Write a binary C or Fortran type record.

A Fortran record compatible with most compilers is structured as follows:

  • a 4-byte integer indicating the number of bytes in the record.
  • the raw data
  • a 4-byte integer indicating the number of bytes in the record.

A C record contains only the raw data.

Parameters
[in]recpointer to location containing data.
[in]sizesize of each item of data in bytes.
[in]ninumber of items to write.
[in]fecs_file_t descriptor.
Returns
the number of items (not bytes) sucessfully written.

Here is the call graph for this function: