lcrzo_file(3)

NAME
lcrzo_file - lcrzo library : files, file descriptors, streams

CONTENTS
/*    Laurent Constantin's network library (lcrzo)
                 lcrzo_file module
  Functions herein allow to open/read/write/close files.
*/
/*-------------------------------------------------------------*/
/* definition of a lcrzo_file. You should not use its
   fields directly. */
typedef struct
{ int fd;
  lcrzo_bool canclosefd;
  lcrzo_bool openforreading;
  lcrzo_bool openforwriting;
  lcrzo_bool dataend;
  lcrzo_data storeddata;
  lcrzo_int32 storeddatasize;
} lcrzo_file;
/*-------------------------------------------------------------*/
/***************************************************************
 * Note about file names :                                     *
 * Under Windows, '/' and '\' are recognized as directory      *
 * separator. However, under Unix, only '/' is valid.          *
 * So, if you want your code to be portable, use '/'.          *
 ***************************************************************/
/*-------------------------------------------------------------*/
/***************************************************************
 * Note about file sizes :                                     *
 * Lcrzo does not support files which have a size > 0x7FFFFFFF *
 * (2Gbytes). Indeed, lcrzo is a network library, and such big *
 * size does not make sense. If a function returns the error   *
 * LCRZO_ERR_SPFILE2G, then you cannot use lcrzo to deal with  *
 * it : just create your own function (dealing for example     *
 * with 64bits sizes).                                         *
 ***************************************************************/
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_open_read
   Description :
     Open a file for reading.
   Input parameter(s) :
     filename : name of the file to open
   Input/output parameter(s) :
   Output parameter(s) :
     *pfile : lcrzo_file which is opened
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_file_open_read(lcrzo_conststring filename,
			 lcrzo_file *pfile);
/* Name : lcrzo_file_open_write
   Description :
     Open a file for writing.
   Input parameter(s) :
     filename : name of the file to open
     mustbeanexistentfile : file must already exist
     mustbeanewfile : file musn't already exist
   Input/output parameter(s) :
   Output parameter(s) :
     *pfile : lcrzo_file which is opened
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_open_write(lcrzo_conststring filename,
			  lcrzo_bool mustbeanexistentfile,
			  lcrzo_bool mustbeanewfile,
			  lcrzo_file *pfile);
/* Name : lcrzo_file_open_append
   Description :
     Open a file for appending.
   Input parameter(s) :
     filename : name of the file to open
     mustbeanexistentfile : file must already exist
   Input/output parameter(s) :
   Output parameter(s) :
     *pfile : lcrzo_file which is opened
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_open_append(lcrzo_conststring filename,
			 lcrzo_bool mustbeanexistentfile,
			 lcrzo_file *pfile);
/* Name : lcrzo_xxx_close
   Description :
     Close a file.
   Input parameter(s) :
     pfile : lcrzo_file to close
     fd : file descriptor to close
     *pstream : FILE to close
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_close(lcrzo_file *pfile);
int lcrzo_fd_close(int fd);
int lcrzo_stream_close(LCRZOFILE *pstream);
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_init_fd
   Description :
     Associate a lcrzo_file to a file descriptor.
     After this function, user has to close the fd and pfile.
   Input parameter(s) :
     fd : file descriptor
   Input/output parameter(s) :
   Output parameter(s) :
     *pfile : lcrzo_file which is associated to fd
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_init_fd(int fd,
                       lcrzo_file *pfile);
/* Name : lcrzo_file_init_stream
   Description :
     Associate a lcrzo_file to a FILE stream.
     After this function, user has to close the fd and pstream.
   Input parameter(s) :
     pstream : FILE
   Input/output parameter(s) :
   Output parameter(s) :
     *pfile : lcrzo_file which is associated to pstream
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_init_stream(LCRZOFILE *pstream,
                           lcrzo_file *pfile);
/* Name : lcrzo_fd_init_file
   Description :
     Associate a file descriptor to a lcrzo_file.
     After this function, user has to close the fd and pfile.
   Input parameter(s) :
     *pfile : lcrzo_file
   Input/output parameter(s) :
   Output parameter(s) :
     *pfd : file descriptor associated to pfile
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_fd_init_file(lcrzo_file *pfile,
                       int *pfd);
/* Name : lcrzo_stream_init_file
   Description :
     Associate a FILE to a lcrzo_file.
     After this function, user has to close the FILE and pfile.
   Input parameter(s) :
     *pfile : lcrzo_file
   Input/output parameter(s) :
   Output parameter(s) :
     *ppstream : FILE associated to pfile
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_stream_init_file(lcrzo_file *pfile,
                           LCRZOFILE **ppstream);
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_write
   Description :
     Write data in a file.
     If datasize is too long, data will be written in several
     chunks (use lcrzo_file_write_msg if you want data to be written
     in one step).
   Input parameter(s) :
     *pfile : lcrzo_file where to write
     data : data to write
     datasize : size of data to write
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_write(lcrzo_file *pfile,
		     lcrzo_constdata data,
		     lcrzo_int32 datasize);
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_write_msg
   Description :
     Write data in a file.
   Input parameter(s) :
     *pfile : lcrzo_file where to write
     data : data to write
     datasize : size of data to write
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_write_msg(lcrzo_file *pfile,
			 lcrzo_constdata data,
			 lcrzo_int32 datasize);
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_readm
   Description :
     Allocate a memory array, and initialize it with
     data read from a file.
   Input parameter(s) :
     *pfile : lcrzo_file where to read
     *pmaxwaitingtime : maximum waiting time (can be a lcrzo_time,
                        LCRZO_WAIT_NODELAY or LCRZO_WAIT_INFINITE)
   Input/output parameter(s) :
   Output parameter(s) :
     *pdataout : pointer which will be malloced (so, the
                 memory will have to be freed by the
                 user with 'free(*pdataout)').
                 The allocated memory will be set with read data
     *pdataoutsize : reached size of *pdataout
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKTEMPDATAEND : the function received nothing
                               before pmaxwaitingtime, so it
			       exited without reading data
*/
int lcrzo_file_readm(lcrzo_file *pfile,
		     lcrzo_time *pmaxwaitingtime,
		     lcrzo_data *pdataout,
		     lcrzo_int32 *pdataoutsize);
/* Name : lcrzo_file_readm_fixed
   Description :
     Allocate a memory array, and initialize it with
     data of fixed size read from a file.
   Input parameter(s) :
     *pfile : lcrzo_file where to read
     *pmaxwaitingtime : maximum waiting time (can be a lcrzo_time,
                        LCRZO_WAIT_NODELAY or LCRZO_WAIT_INFINITE)
     datasizetoread : size to read
   Input/output parameter(s) :
   Output parameter(s) :
     *pdataout : pointer which will be malloced (so, the
                 memory will have to be freed by the
                 user with 'free(*pdataout)').
                 The allocated memory will be set with read data
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKTEMPDATAEND : the function received nothing
                               before pmaxwaitingtime, so it
			       exited without reading data
*/
int lcrzo_file_readm_fixed(lcrzo_file *pfile,
			   lcrzo_time *pmaxwaitingtime,
			   lcrzo_int32 datasizetoread,
			   lcrzo_data *pdataout);
/* Name : lcrzo_file_readm_line
   Description :
     Allocate a memory array, and initialize it with
     data read from a file. We stop at first '\r' or '\n' (which
     is not stored in data).
   Input parameter(s) :
     *pfile : lcrzo_file where to read
     *pmaxwaitingtime : maximum waiting time (can be a lcrzo_time,
                        LCRZO_WAIT_NODELAY or LCRZO_WAIT_INFINITE)
   Input/output parameter(s) :
   Output parameter(s) :
     *pdataout : pointer which will be malloced (so, the
                 memory will have to be freed by the
                 user with 'free(*pdataout)').
                 The allocated memory will be set with read data
     *pdataoutsize : reached size of *pdataout
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKTEMPDATAEND : the function received nothing
                               before pmaxwaitingtime, so it
			       exited without reading data
*/
int lcrzo_file_readm_line(lcrzo_file *pfile,
			  lcrzo_time *pmaxwaitingtime,
			  lcrzo_data *pdataout,
			  lcrzo_int32 *pdataoutsize);
/*-------------------------------------------------------------*/
/* file types */
/* regular file */
#define LCRZO_FILE_TYPE_REG   1
/* directory */
#define LCRZO_FILE_TYPE_DIR   2
/* unix link */
#define LCRZO_FILE_TYPE_LINK  3
/* unix socket */
#define LCRZO_FILE_TYPE_SOCK  4
/* other type */
#define LCRZO_FILE_TYPE_OTHER 5
/* Name : lcrzo_xxx_type
   Description :
     Get type of a file.
   Input parameter(s) :
     *filename : filename
     *pfile : lcrzo_file
   Input/output parameter(s) :
   Output parameter(s) :
     *ptype : type of the file
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_filename_type(lcrzo_conststring filename,
			lcrzo_int16 *ptype);
int lcrzo_file_type(lcrzo_file *pfile,
		    lcrzo_int16 *ptype);
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_flush
   Description :
     Flush a file.
   Input parameter(s) :
     *pfile : lcrzo_file
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_flush(lcrzo_file *pfile);
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_offset_get
   Description :
     Get offset of a file.
   Input parameter(s) :
     *pfile : lcrzo_file
   Input/output parameter(s) :
   Output parameter(s) :
     *poffset : offset of the file
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_offset_get(lcrzo_file *pfile,
			  lcrzo_int32 *poffset);
/* Name : lcrzo_file_offset_set
   Description :
     Set offset of a file.
   Input parameter(s) :
     *pfile : lcrzo_file
     offset : offset of the file
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_file_offset_set(lcrzo_file *pfile,
			  lcrzo_int32 offset);
/*-------------------------------------------------------------*/
/* Name : lcrzo_xxx_size
   Description :
     Get size of a file.
   Input parameter(s) :
     *filename : filename
     *pfile : lcrzo_file
   Input/output parameter(s) :
   Output parameter(s) :
     *psize : size of the file
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_filename_size(lcrzo_conststring filename,
			lcrzo_int32 *psize);
int lcrzo_file_size(lcrzo_file *pfile,
		    lcrzo_int32 *psize);
/*-------------------------------------------------------------*/
/* Name : lcrzo_filename_exist
   Description :
     Check if a file exists.
   Input parameter(s) :
     *filename : filename
   Input/output parameter(s) :
   Output parameter(s) :
     *pyes : if file exists
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_filename_exist(lcrzo_conststring filename,
			 lcrzo_bool *pyes);
/*-------------------------------------------------------------*/
/* Name : lcrzo_filename_create
   Description :
     Create an empty file.
   Input parameter(s) :
     *filename : filename
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_filename_create(lcrzo_conststring filename);
/*-------------------------------------------------------------*/
/* Name : lcrzo_filename_remove
   Description :
     Remove a file.
   Input parameter(s) :
     *filename : filename
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_filename_remove(lcrzo_conststring filename);
/*-------------------------------------------------------------*/
/* Name : lcrzo_filename_rename
   Description :
     Rename a file.
   Input parameter(s) :
     *oldfilename : old filename
     *newfilename : new filename
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_filename_rename(lcrzo_conststring oldfilename,
			  lcrzo_conststring newfilename);
/*-------------------------------------------------------------*/
/* Name : lcrzo_filename_copy
   Description :
     Copy a file.
   Input parameter(s) :
     *oldfilename : old filename
     *newfilename : new filename
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_filename_copy(lcrzo_conststring oldfilename,
			lcrzo_conststring newfilename);
/* Name : lcrzo_file_copy
   Description :
     Copy a file.
   Input parameter(s) :
     *pfile : source file to copy from
     *newfilename : new filename
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_file_copy(lcrzo_file *pfile,
		    lcrzo_conststring newfilename);
/*-------------------------------------------------------------*/
/* Name : lcrzo_file_truncate
   Description :
     Truncate a file.
   Input parameter(s) :
     *filename : filename
     *pfile : lcrzo_file
     size : size to truncate
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_filename_truncate(lcrzo_conststring filename,
			    lcrzo_int32 size);
int lcrzo_file_truncate(lcrzo_file *pfile,
			lcrzo_int32 size);
/*-------------------------------------------------------------*/
/* Name : lcrzo_filename_read
   Description :
     Read all data from a file.
   Input parameter(s) :
     *filename : filename
   Input/output parameter(s) :
   Output parameter(s) :
     *pdata : pointer which will be malloced (so, the
              memory will have to be freed by the
              user with 'free(*pdata)').
              The allocated memory will be set with data
	      from the file
     *pdatasize : reached size of *pdata
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : file was not found
*/
int lcrzo_filename_read(lcrzo_conststring filename,
			lcrzo_data *pdata,
			lcrzo_int32 *pdatasize);
/* Name : lcrzo_filename_write
   Description :
     Write data in a file.
   Input parameter(s) :
     *filename : filename
     mustbeanexistentfile : file must already exist
     mustbeanewfile : file musn't already exist
     data : data to write
     datasize : size of data to write
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_filename_write(lcrzo_conststring filename,
		     lcrzo_bool mustbeanexistentfile,
		     lcrzo_bool mustbeanewfile,
		     lcrzo_constdata data,
		     lcrzo_int32 datasize);
/* Name : lcrzo_filename_append
   Description :
     Append data in a file.
   Input parameter(s) :
     *filename : filename
     mustbeanexistentfile : file must already exist
     data : data to append
     datasize : size of data to append
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_filename_append(lcrzo_conststring filename,
		      lcrzo_bool mustbeanexistentfile,
		      lcrzo_constdata data,
		      lcrzo_int32 datasize);
/*-------------------------------------------------------------*/
/*-------------------------------------------------------------*/
/* Name : lcrzo_dir_exist
   Description :
     Check if a directory exist.
   Input parameter(s) :
     *dirname : name of the directory
   Input/output parameter(s) :
   Output parameter(s) :
     *pyes : true if directory exists
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_dir_exist(lcrzo_conststring dirname,
		    lcrzo_bool *pyes);
/*-------------------------------------------------------------*/
/* Name : lcrzo_dir_create
   Description :
     Create a directory.
     Warning : this function is not secured against
               symlink races
   Input parameter(s) :
     *dirname : name of the directory
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_dir_create(lcrzo_conststring dirname);
/* Name : lcrzo_dir_remove
   Description :
     Remove a directory.
     Warning : this function is not secured against
               symlink races
   Input parameter(s) :
     *dirname : name of the directory
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_dir_remove(lcrzo_conststring dirname);
/* Name : lcrzo_dir_rename
   Description :
     Rename a directory.
     Warning : this function is not secured against
               symlink races
   Input parameter(s) :
     *olddirname : previous name of the directory
     *newdirname : new name for the directory
   Input/output parameter(s) :
   Output parameter(s) :
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_dir_rename(lcrzo_conststring olddirname,
		     lcrzo_conststring newdirname);
/*-------------------------------------------------------------*/
/* Name : lcrzo_dir_count
   Description :
     Count the number of files in a directory.
   Input parameter(s) :
     *dirname : name of the directory
   Input/output parameter(s) :
   Output parameter(s) :
     *pcount : number of files
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : directory was not found
*/
int lcrzo_dir_count(lcrzo_conststring dirname,
		    lcrzo_int32 *pcount);
/**********************************************
 * Note about positions :                     *
 * Warning : 0 is an invalid value            *
 * Here are possible values for a position :  *
 *  +1 : first item                           *
 *  +2 : second item                          *
 *  ...                                       *
 * Moreover, we can count from the end :      *
 *  -1 : last item                            *
 *  -2 : last but one item                    *
 *  ...                                       *
 **********************************************/
/* Name : lcrzo_dir_value_pos
   Description :
     Get the name of the file situated at a given position.
   Input parameter(s) :
     *dirname : name of the directory
     pos : wanted position
   Input/output parameter(s) :
   Output parameter(s) :
     *pfilename : mallocated string containing the file
                  name at position pos
   Normal return values :
     LCRZO_ERR_OK : ok
     LCRZO_ERR_OKFILENOTFOUND : directory was not found
*/
int lcrzo_dir_value_pos(lcrzo_conststring dirname,
			lcrzo_int32 pos,
			lcrzo_string *pfilename);
/*-------------------------------------------------------------*/
/* Name : lcrzo_filename_clean
   Description :
     Clean a filename ("//"->"/", "/./"->"/", "/aa/../"->"/", etc.).
   Input parameter(s) :
     filename : filename (ex : "/tmp/dir/..//./file")
   Input/output parameter(s) :
   Output parameter(s) :
     *pcleanedfilename : cleaned filename (ex : "/tmp/file")
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_filename_clean(lcrzo_conststring filename,
			 lcrzo_string *pcleanedfilename);
/* Name : lcrzo_filename_parentdir
   Description :
     Set the directory name of a path.
   Input parameter(s) :
     filename : filename (ex : "/tmp/file")
   Input/output parameter(s) :
   Output parameter(s) :
     *pparentdir : directory name (ex : "/tmp")
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_filename_parentdir(lcrzo_conststring filename,
			     lcrzo_string *pparentdir);
/* Name : lcrzo_filename_lastfile
   Description :
     Set the file name of a path.
   Input parameter(s) :
     filename : filename (ex : "/tmp/file")
   Input/output parameter(s) :
   Output parameter(s) :
     *plastfile : file name (ex : "file")
   Normal return values :
     LCRZO_ERR_OK : ok
*/
int lcrzo_filename_lastfile(lcrzo_conststring filename,
			    lcrzo_string *plastfile);

SEE ALSO
lcrzo(3), lcrzo_types(3), lcrzo_data(3), lcrzo_string(3), lcrzo_time(3), lcrzo_file(3), lcrzo_address(3), lcrzo_device(3), lcrzo_list(3), lcrzo_process(3), lcrzo_ipc(3), lcrzo_header(3), lcrzo_ipopt(3), lcrzo_tcpopt(3), lcrzo_packet(3), lcrzo_icmp(3), lcrzo_print(3), lcrzo_record(3), lcrzo_conf(3), lcrzo_spoof(3), lcrzo_sniff(3), lcrzo_sock(3), lcrzo_wait(3), lcrzo_global(3), lcrzo_error(3) lcrzo_misc(3), lcrzo_obso(3),