Main Page   Alphabetical List   Data Structures   File List   Data Fields   Globals   Examples  

files.h File Reference

Go to the source code of this file.

Defines

#define FILES_UTIL_INIT_BUFF_SIZE   2048
 This value is used by various functions that need to allocate buffers. This represents the initial size of the buffer (in bytes).

#define FILES_UTIL_MALLOC_ERR   -1
 Return value for the function read_file(). The function can not allocate memory.

#define FILES_UTIL_READ_ERR   -2
 Return value for the function read_file(). An error occured while reading the input file.

#define FILES_UTIL_OPEN_ERR   -3
 Return value for the function read_file(). Can not open the input file.

#define SET_TIMEOUT_FILE_OPEN_ERROR   -4
 Return value for the function set_timeout_file(). Can not open target file.

#define SET_TIMEOUT_FILE_WRITE_ERROR   -5
 Return value for the function set_timeout_file(). An error occured while writing into the target file.

#define SET_TIMEOUT_FILE_OK   -6
 Return value for the function set_timeout_file(). Timeout file set correctly.

#define TEST_TIMEOUT_FILE_TIMEOUT_ELLAPSED   -7
 Return value for the function test_timeout_file(). The timeout is passed.

#define TEST_TIMEOUT_FILE_READ_ERROR   -8
 Return value for the function test_timeout_file(). An error occured while reading the timeout file.

#define TEST_TIMEOUT_FILE_TIMEOUT_NOT_ELLAPSED   -9
 Return value for the function test_timeout_file(). The timeout is not passed (you may have to wait).

#define TEST_TIMEOUT_FILE_UNLINK_FAILED   -10
 Return value for the function test_timeout_file(). The function could not delete the timeout file.

#define FILES_HD

Functions

int wait_for_file (char *file_name, int period, char *stop_file)
 Wait for a file to appear.

char * wait_for_multiple_file (char **file_names, int period, char *stop_file)
 Wait for a file (within a list of files) to exist.

int read_file (char *file_name, char **buff)
 Load the content of a file into an in-memory buffer.

int set_timeout_file (char *filename)
 Set the timeout file that contains the current number of seconds since January 1970 00:00:00.

int test_timeout_file (char *filename, int timeout)
 Look at a timeout file to see if the calling process should wait or go ahead.

void basename (char *src, char *dst)
 Extract the base name of a given file name.


Detailed Description

Header file for file.c.

Definition in file files.h.


Function Documentation

void basename char *    src,
char *    dst
 

Extract the base name of a given file name.

Parameters:
src Pointer to a zero terminated string of characters that represents the name of the file.
dst Pointer to a memory location that will be sued to store a zero terminated string of characters that is the base name of the file.
Warning:
No test is done regarding the size of the memory chunck pointed by dst. It is your responsability to allocate enough memory for the resulting string of characters!

Definition at line 260 of file files.c.

int read_file char *    file_name,
char **    buff
 

Load the content of a file into an in-memory buffer.

Parameters:
file_name Pointer to a zero terminated file that represents the name of the file to load..
buff Pointer to a pointer that will be used to save the file's content.
Returns:
If the function succed, the function returns a positive interger that represents the number of bytes extracted from the file. If the function failes, then it returns a negative integer. This integer could be:
  • FILES_UTIL_MALLOC_ERR
  • FILES_UTIL_READ_ERR
Warning:
The memory pointed by 'buff' has been allocated within the function, therefore you must free it yourself (using free()).

Definition at line 96 of file files.c.

References FILES_UTIL_INIT_BUFF_SIZE, FILES_UTIL_MALLOC_ERR, FILES_UTIL_OPEN_ERR, and FILES_UTIL_READ_ERR.

int set_timeout_file char *    filename
 

Set the timeout file that contains the current number of seconds since January 1970 00:00:00.

Parameters:
filename Pointer to a zero terminated string of characters that represents the path to the file.
Returns:
The function returns one of the following values:
  • SET_TIMEOUT_FILE_OPEN_ERROR: Can not open the target file 'filename'.
  • SET_TIMEOUT_FILE_WRITE_ERROR: Error while writing in the target file.
  • SET_TIMEOUT_FILE_OK: The function succed.

Definition at line 159 of file files.c.

References SET_TIMEOUT_FILE_OK, SET_TIMEOUT_FILE_OPEN_ERROR, and SET_TIMEOUT_FILE_WRITE_ERROR.

int test_timeout_file char *    filename,
int    timeout
 

Look at a timeout file to see if the calling process should wait or go ahead.

Parameters:
filename Pointer to a zero terminated string of characters that represents the timeout file.
timeout Integer value that represents the timeout in seconds.
Returns:
The function returns one of the following values:
  • TEST_TIMEOUT_FILE_TIMEOUT_ELLAPSED: The timeout is passed.
  • TEST_TIMEOUT_FILE_READ_ERROR: An error occured while reading the timeout file.
  • TEST_TIMEOUT_FILE_TIMEOUT_NOT_ELLAPSED: The timeout is not passed yet.
  • TEST_TIMEOUT_FILE_UNLINK_FAILED: An error occured while removing the timeout file.
Warning:
The timeout file should have been set by using the function set_timeout_file().

Definition at line 198 of file files.c.

References TEST_TIMEOUT_FILE_READ_ERROR, TEST_TIMEOUT_FILE_TIMEOUT_ELLAPSED, TEST_TIMEOUT_FILE_TIMEOUT_NOT_ELLAPSED, and TEST_TIMEOUT_FILE_UNLINK_FAILED.

int wait_for_file char *    file_name,
int    period,
char *    stop_file
 

Wait for a file to appear.

Parameters:
file_name Name of the file.
period The function test if the file exists periodically. If the file does not exist, then the process is put to sleep for a certain amount of time, and then the function tests the file existence again ... and so on. Between each test, the process is put to sleep for 'period' seconds.
stop_file If the file that name is defined by 'stop_file' exists, then the function exists and returns 1.
Returns:
If the file represented by 'file_name' exists, the function return 0. If the file represented by 'stop_file' exists, the the function returns 1.
Warning:
This function uses the system call access() to test the existence of a file. According to the documentation, this system call can be interrupted by a signal. But in this case the return value is -1, which is also the return value if the file does not exist. Therefore we do not have to perform any special action in case the system call is interrupted ... we just try again.

Definition at line 21 of file files.c.

char* wait_for_multiple_file char **    file_names,
int    period,
char *    stop_file
 

Wait for a file (within a list of files) to exist.

Parameters:
file_names This variable represents the list of file names to test. It is an array of strings, each string represents a file name. The last element of the list MUST be set to NULL.
period The function test if the file exists periodically. If the file does not exist, then the process is put to sleep for a certain amount of time, and then the function tests the file existence again ... and so on. Between each test, the process is put to sleep for 'period' seconds.
stop_file If the file that name is defined by 'stop_file' exists, then the function exists and returns 1.
Returns:
If one of the files specified in the list of files exists, the function returns a non NULL pointer that points a the name of the file. If the file represented by 'stop_file' exists, the the function returns NULL.
Warning:
The last element of the list of file names MUST be set to NULL. If you want to wait on 3 files, then the variable 'file_names' must be an array of 4 elements: the 3 file names and the last NULL pointer.

Definition at line 53 of file files.c.


Generated on Thu Apr 3 16:23:45 2003 for Common_C_libraries by doxygen1.3-rc1