file.h
=============================================================================

    This manual convers all file-related routines which are prototyped
    in the file.h header.


    FILE_APPCHR
    -------------------------------------------------------------------------

        Summary  Appends a character to pathname

        Syntax   char* file_appchr(char *dst, const char *src, char ch='\\');

        Remarks  This function appends the character 'ch' to 'dst' (if the
                 'src' parameter is not NULL, it copies 'src' to 'dst' first)
                 only if the character is not there already. This is very
                 useful for appending trailing backslashes in pathnames.

        Return   dst


    FILE_APPEND
    -------------------------------------------------------------------------

        Summary  Appends one file to another

        Syntax   int file_append(const char *dest, const char *src);

        Remarks  Appends the file 'src' to the file 'dest'. If the file
                 'dest' does not exist, it is created. Attempts to append
                 to the same file as the 'src' will result in an undefined
                 behavior. Files are processed in binary mode.

        Return   On success, returns 0; on error, returns -1


    FILE_BACKUP
    -------------------------------------------------------------------------

        Summary  Duplicate file with .BAK extension

        Syntax   Boolean file_backup(const char *fileName);

        Remarks  This function copies the file 'fileName' to a new file with
                 the same name, but with an extension of ".BAK". If such a
                 file already exists, it will be overwritten.

        Return   On success, returns True; False otherwise


    FILE_CHDIR
    -------------------------------------------------------------------------

        Summary  Change current directory

        Syntax   int file_chdir(char *path);

        Remarks  This function is the same as the standard library's chdir()
                 but it also works across drives (which the former does not).
                 The 'path' argument specifies the path to change to, with
                 an optional drive designation.

        Return   On success, returns 0; otherwise returns -1


    FILE_CHEXT
    -------------------------------------------------------------------------

        Summary  Change or remove the extension in a name specification

        Syntax   char* file_chext(char *dest, const char *src,
                                  const char *ext );

        Remarks  This function changes the extension in the 'src' path
                 specification to 'ext' while copying it to 'dest' (which
                 must be large enough to accomodate the result). If 'ext'
                 is NULL, this function will remove the existing extension.
                 Note that the 'ext' parameter must include the dot as part
                 of the extension (e.g. ".SRC" as opposed to "SRC").

        Return   dest


    FILE_CMPDATE
    -------------------------------------------------------------------------

        Summary  Compares the time stamps on two files

        Syntax   int file_cmpdate(const char *p1, const char *p2);

        Remarks  This function compares the time stamps on files specified
                 by the 'p1' and 'p2' parameters. Both files must exist or
                 the results will be undefined.

        Return   < 0, p1 is newer than p2
                 = 0, p1 and p2 have the same date and time stamps
                 > 0, p2 is older than p2


    FILE_COPY
    -------------------------------------------------------------------------

        Summary  Copies one file to another

        Syntax   int file_copy(const char *dest, const char *src);

        Remarks  This function copies the file 'src' to 'dest', overwriting
                 the destination if it already exists. If 'src' does not
                 exist, the behavior is undefined (i.e. 'dest' will still
                 be truncated to 0 bytes in size).

        Return   On success, returns 0; -1 otherwise


    FILE_DIREXIST
    -------------------------------------------------------------------------

        Summary  Checks if a directory exists

        Syntax   Boolean file_direxist(const char *dirSpec);

        Remarks  Checks if a directory 'dirSpec' exists. The specification
                 can be optionally terminated with a backslash.

        Return   True if the directory exists; False otherwise


    FILE_DIRSPEC
    -------------------------------------------------------------------------

        Summary  Exrtact the path portion from a file name

        Syntax   char* file_dirspec(const char *path);

        Remarks	 Extract the path portion from the 'path' fully qualified
                 pathname. The returned string will always be terminated
                 with a backslash. Note that since a local static buffer
                 is used to store the path portion, it will be overwritten
                 with each call to this routine. The maximum allowable
                 length of the path is 80 characters.

        Return   The path portion, terminated with a backslash


    FILE_EXIST
    -------------------------------------------------------------------------

        Summary  Checks if a file exists

        Syntax   Boolean file_exist(const char *fileName);

        Remarks  This function checks if the file 'fileName' exists. It does
                 not check write permissions, just verifies the existence
                 of the file. The file is not opened by this call.

        Return   True if the file exists; False otherwise


    FILE_EXTEND
    -------------------------------------------------------------------------

        Summary  Extends a file by a number of bytes

        Syntax   Boolean file_extend(const char *fileName, long width);

        Remarks  This function will extend the file 'fileName' by 'width'
                 bytes. The added space will be filled with zeroes.

        Return   On success, returns True; False otherwise


    FILE_KILLEMPTY
    -------------------------------------------------------------------------

        Summary  Zap file of zero length

        Syntax   void file_killempty(char* fileName);

        Remarks  This macro deletes the file 'fileName' if its size is 0
                 bytes. Very useful for removing those pesky non-files which
                 sometimes result from unexpected program termination. Note
                 that the file will be removed regardless of its access
                 permissions.

        Return   Nothing


    FILE_MKDIR
    -------------------------------------------------------------------------

        Summary  Create a directory

        Syntax   int file_mkdir(char *path);

        Remarks  This function works much like the standard mkdir(), except
                 that if any of the directories in the 'path' specification
                 do not exist, they will be created. This allows for creation
                 of nested directories with a single call.

        Return   On success, returns 0; -1 otherwise


    FILE_NAME
    -------------------------------------------------------------------------

        Summary  Extract the file name portion of a path

        Syntax   char* file_name(const char *path);

        Remarks  This function extracts the file name portion of a fully
                 qualified path specification. Note that it does not copy
                 anything to internal buffers, but rather simply returns
                 a pointer to the correct location in the 'path' argument.

        Return   Pointer to beginning of file name in 'path'


    FILE_REMOVE
    -------------------------------------------------------------------------

        Summary  Removes a file

        Syntax   int file_remove(const char *spec);

        Remarks  This function removes the file(s) in 'spec' (wildcards can
                 be used). Note that the file(s) will be removed regardless
                 of their current attributes (that is, read-only, system or
                 hidden files will be deleted as well). This function will
                 not remove directories.

        Return   On success, returns 0; -1 otherwise


    FILE_RENAME
    -------------------------------------------------------------------------

        Summary  Renames a file

        Syntax   int file_rename(const char *oldname, const char *newname );

        Remarks  This function is very similar to the standard library's
                 rename() except it works correctly accross drives (that is,
                 the file will be copied to the new drive and then deleted).
                 Note that if 'newname' exists, the function will fail unless
                 the drives are different; in that case the 'newname' file
                 will be overwritten.

        Return   On success, returns 0; -1 otherwise


    FILE_RMDIR
    -------------------------------------------------------------------------

        Summary  Removes a directory

        Syntax   int file_rmdir(char *path);

        Remarks  This is a very powerful and dangerous function. It can
                 delete a whole directory tree. This routine will remove
                 'path' directory (trailing backslash is not necessary),
                 with all its subdirectories and files. Note that unlike
                 the rmdir() in the library or even the MS-DOS rd command,
                 this WILL remove all files along the way, regardless of
                 their attributes.

        Return   On success, returns 0; -1 otherwise


    FILE_SCAN
    -------------------------------------------------------------------------

        Summary  Search a path list for a given file

        Syntax   char* file_scan(const char *pathList, const char *fileName);

        Remarks  This function searches the paths listed in 'pathList' for
                 a file 'fileName'. The path list is a string with several
                 path specification separated by semi-colon (like the PATH
                 environment in MS-DOS). If 'pathList' is NULL, this routine
                 will search the current directory and then all the paths
                 from the PATH environment variable. The routine uses a
                 local static buffer to store the fully-qualified file name.
                 This buffer is overwritten with each call.

        Return   On success, returns full file path; NULL otherwise


    FILE_SIZE
    -------------------------------------------------------------------------

        Summary  Returns the size of a file

        Syntax   long file_size(const char *fileSpec);

        Remarks  This function will return the file size (in bytes) for
                 the file 'fileSpec'. Note that the routine supports wild-
                 cards in its argument. In this case, the sum of the sizes
                 of all files which match the specification will be returned.

        Return   On success, returns size in bytes; 0 if no files found


    FILE_TEMPNAME
    -------------------------------------------------------------------------

        Summary  Creates a unique file name

        Syntax   char* file_tempname(void);

        Remarks  This function creates a unique file name. It will use the
                 TEMP or TMP environment variables (if available) to get
                 the name of the directory to use. If none of these is
                 present, it will default to the current directory. Note
                 that this routine uses a static buffer for the name it
                 creates. This is overwritten with each call. Note also that
                 the file is not actually created. The function verifies that
                 it is possible to do it.

        Return   On success, unique file name; NULL otherwise


    FILE_UNIQUE
    -------------------------------------------------------------------------

        Summary  Create a unique file name for a specific directory

        Syntax   char* file_unique(char *directory);

        Remarks  This function creates a filename specification which is
                 unique for the 'directory' given. The file is not actually
                 created by the function, its name simply guaranteed to be
                 unique for the directory. This routine uses a local static
                 buffer to store the result (and return it). This buffer is
                 overwritten with each call. The file name will consist of
                 8 hexadecimal numbers and will have a ".TMP" extension.

        Return   On success, unique file name; NULL otherwise


    FILE_READ
    -------------------------------------------------------------------------

        Summary  Reads a record from a file

        Syntax   Boolean file_read(FILE *fp, Type *rec, long recno = -1);

        Remarks  This is a templatized function which can be used to read
                 a specific record from a typed binary file. The file can
                 be accessed in sequential or random-access order. The 'fp'
                 argument must point to a file previously open for reading.
                 The 'rec' parameter points to an area of 'Type' which will
                 store the result. The 'recno' parameter determines which
                 record to read. If the default value of -1 is used, the
                 record is read from the current position in the file. Any
                 other value will reposition the file pointer and retrieve
                 the specified record number. Note that records are numbered
                 from 0. If the specified record number is invalid, the
                 contents of the 'rec' buffer are undefined.

        Return   On success, returns True; False otherwise


    FILE_WRITE
    -------------------------------------------------------------------------

        Summary  Writes a record to a file

        Syntax   Boolean file_write(FILE *fp, Type *rec, long recno = -1);

        Remarks  This templatized function writes a record to a typed binary
                 file. The writes can be performed in random or sequential
                 order. The 'fp' argument must point to a file previously
                 open for update. The 'rec' parameter points to an area of
                 'Type' type which holds the data to be written out. The
                 'recno' argument determines which record to update. If the
                 default value of -1, the write is done at the current
                 position in the file. Any other value will cause the
                 routine to reposition the file pointer and then write the
                 record. Note that records are numbered from 0. Also note
                 that it is possible to extend the file with new records,
                 but this can be done one record at a time, by writing in
                 sequential order at the end of the file only.

        Return   On success, returns True; False otherwise

