category-group: files
layer: 0
header file(s): z_filesubs.h
libraries: libz00.lib

synopsis.
basic file and directory operations. This includes getting and setting the 'current working directory - the spot in the file system the program is attached to. The functions here use char buffers, eg "char filename[80];". Most of the functions here have counterparts at higher layers that are members of class objects.

[C] functions (aka subroutines):

z_file_exists()
SIGNATURE: boolean z_file_exists (const char *path, int *pie = NULL)
SYNOPSIS:
checks the existence of a file in the file system, given a path. the path should include all directories leading up to the file, either fully-qualified (starting at the root directory), or relative to the currently-running program. the final part of the string is the file name itself. The text should be written in the style appropriate to the OS (unix: forward-slash; Microsoft: back-slash)
PARAMETERS
  • pie - error indicator output variable. values:
    0: file found
    1: no such file
    -1: internal error
    • RETURNS:
    TRUE: file exists
    FALSE: no such file (or error!)
     

    z_directory_exists()
    SIGNATURE: boolean z_directory_exists (const char *path, int *pie = NULL)
    SYNOPSIS:
    checks for the existence of a directory. see z_file_exists() for a discussion on the formatting of the path parameter.
    PARAMETERS

    • pie - error indicator output variable. values:
      0: ok; directory is bona-fide;
      1: does not exist;
      2: entry exists, but it is not a directory
    • path - the directory, as a string. This value should be either the fully-qualified path (including the directory itself), or a valid path relative to the current program.
    RETURNS:
    TRUE: directory exists
    FALSE: no such directory (or error)
     

    z_create_file()
    SIGNATURE: int z_create_file (const char *, int * = NULL)
    SYNOPSIS: creates a file. the file created as read and write permission.
    DESCRIPTION:
    This function is a wrapper around OS calls, such as "creat()" [unix] and "_create()" [microsoft]. The unix version "chmods" the permission mask to 0666. Previously existing files are overwritten.
     

    z_create_directory()
    SIGNATURE: int z_create_directory (const char *, int * = NULL)
    SYNOPSIS: creates a file. the file created as read and write permission.
    DESCRIPTION:
    This function is clearly a wrapper around OS calls, such as "creat()" [unix] and "_create()" [microsoft]. The unix version chmods the file to 0666. Previously existing files are overwritten.
     

    z_delete_file()
    SIGNATURE: int z_delete_file (const char *, int *pe = NULL)
    SYNOPSIS: deletes a given file from the file system, given a path to it
    RETURNS:
    0: successful deletion
    -1: failure (no such file)
     

    z_delete_directory()
    SIGNATURE: int z_delete_directory (const char *dirname, int *pe = NULL)
    SYNOPSIS: deletes a given directory from the file system. the directory must be empty in order for this subroutine to work.
    RETURNS:
    0: successful deletion
    -1: failure (no such directory, or not empty)
     

    z_rename_file()
    SIGNATURE: int z_rename_file (const char *oldname, const char *newname, int *pe = NULL)
    SYNOPSIS: changes the name of a given file. this is not intended to be used to move a file to a new [directory] location
    RETURNS:
    0: successful rename
    -1: failure (no such file)
     

    z_rename_directory()
    SIGNATURE: int z_rename_directory (const char *oldname, const char *newname, int *pe = NULL)
    SYNOPSIS: deletes a given directory from the file system. the directory must be empty in order for this subroutine to work.
    PARAMETERS

    • oldname - the name of the directory to rename
    • newname - the name to change the directory to
    • pe - error indicator output variable. values:
      0: rename successful
      1: no such directory
      2: error in renaming process
      3: not implemented
    DESCRIPTION: changes the name of a given directory. This is not intended to be used to move a directory to a new [directory] location
    RETURNS:
    0: successful rename
    -1: failure (no such directory)
     

    z_filesize()
    SIGNATURE: size_t z_filesize (const char *fname, int *pie)
    SYNOPSIS: returns size of a file (in bytes)
    PARAMETERS

    • fname - the [full path] name of the file to examine
    • pie - error indicator output variable. values:
      0: success
      1: no such file
      2: could not open the file
      3: error getting file length
    RETURNS:
    number of bytes in the file, if it could be successfully read. if not, output parameter "pie" will be set to a non-zero value and 0 will be returned.
     

    z_currdir()
    SIGNATURE: int z_currdir (char *s_dir, size_t n, int *pi = NULL)
    SYNOPSIS:
    gets the path of the program's current working directory. The notion of the current workind directory is that a program begins its life born from a file residing on a disk drive storage system, and that the directory containing that file becomes the [initial] "current working directory". This subroutine is basically a wrapper for the OS API function. There are a family of OS functions, all similar, that provide the current workind directory path, including getwd(), getcwd(), and _getcwd().
    PARAMETERS

    • s_dir - the path of the directory representing the process's current directory.
    • n - length of "s_dir"
    • pi - [optional] error indicator variable. possible values: 0: got it successfully
      zErr_Param_BadVal: bad parameter provided
      zErr_Param_NullPointer: null pointer parameter provided
      zErr_Syscall_Failure: OS function call error [unspecific]
      zErr_Result_TooBig: resultant path too big for output buffer supplied
    RETURNS:
    0: success
    -1: error: a parent directory could not be read
    -2: error: size is 0 or bad buffer pointer provided
    -3: error: not enough room in output buffer
    TRAITS: the output value ('pi') needs to be worked on
     

    z_set_curdir()
    SIGNATURE: int z_set_curdir (char *path, int *pi)
    SYNOPSIS:
    sets the working directory (see z_currdir() for a discussion about the 'working directory'). This subroutine maps onto the "chdir()" family of OS API functions.
    PARAMETERS

    • path - the path of the directory that the caller wants to
    • set the process's current directory to be;
    • pi - [optional] error indicator variable. possible values: 0: success zErr_Param_NullPointer: null pointer parameter provided
      zErr_Syscall_Failure: OS function call error
     

    RETURNS:
    0: success; current working directory set to 'path'
    -1: error: working directory not changed
    TRAITS: the output value ('pi') needs a lot of work
     

    z_dflt_tmp_directory()
    SIGNATURE: int z_dflt_tmp_directory (char *, int *)
    SYNOPSIS: establishes a [new] directory for temporary files
    TRAITS: not properly developed; rarely used; not recommended
     

    usage.
    In almost all or these functions the last function parameter is of type "int *". Pass a pointer to an int, like so: 

      int retval, errvar;
  retval = z_set_currdir ("c:\\temp", &errvar);
  if (retval)
      { /* check 'errvar' */ }
    The function will give an over-all answer of 0 for success or -1 for failure, and if it succeeds, "errvar" will be 0. If it fails, "errvar" will have a non-zero value (typically a low positive value like 1, 2, or 3) which will provide a clue as to why the call failed.

    history. 

    Sat 01/22/1994: some clean up
Fri 11/07/1997: z_directory_exists() created
Wed 03/03/1999: functions ported to microsoft visual c++
Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_")
Fri 08/22/2003: porting to Win32 + gcc
Sun 03/27/2011: added z_delete_directory()