path.c

   File         : path.c
   Description  : General file/path utilities
   Category     : Utility
   Author       : Charles Yates

   int PATH_FileExists( char *file )
 
   Function     : PATH_FileExists
   Description  : Indicates whether the file exists or not
   Input        : char *file - file to check on
   Output       : void
   Returns      : non-zero if true

   int PATH_IsDir( char *dir )
 
   Function     : PATH_IsDir
   Description  : Indicates whether the dir exists (as a directory)
   Input        : char *dir - dir to check on
   Output       : void
   Returns      : non-zero if true

   char *PATH_Join( char *dir, char *file )
 
   Function     : PATH_Join
   Description  : Joins the directory with the file specified
   Input        : char *dir - directory
                  char *file - file
   Output       : void
   Returns      : char * - string with joined contents
   Comments     : The returned value must be freed

   int PATH_FileInDirectory( char *dir, char *file )
 
   Function     : PATH_FileInDirectory
   Description  : Checks if the specified file is located in
                  the given directory
   Input        : char *dir - directory
                  char *file - file to check on
   Output       : void
   Returns      : non-zero if true

   char *PATH_Locate( char *path, char *file )
 
   Function     : PATH_Locate
   Description  : Locate and return the location of a file on a 
                  given PATH spec (assumed to follow the UNIX
                  convention of dir1:dir2:dir3)
   Input        : char *path - path spec
                  char *file - file
   Output       : void
   Returns      : char * - the full file spec of the located file or NULL
   Comments     : Make sure the returned location is freed

   int PATH_MkDir( char *dir )
 
   Function     : PATH_MkDir
   Description  : Equivalent of mkdir -p
   Input        : char *dir - dir to make
   Output       : directory is created
   Returns      : 0 on success

   char *PATH_ChangeToParent( char *spec )
 
   Function     : PATH_ChangeToParent
   Description  : Equivalent of /parent/dir/.. but it physically changes 
                  the input to /parent
   Input        : char *spec - dir to change
   Output       : directory is created
   Returns      : 0 on success
   Comments     : If the input spec is /parent/file, the output is /parent
                  If the input spec is /parent/dir, the output is /parent
                  If the input spec is /parent/dir/, the output is /parent
                  If the input spec is /, the output is /

   char *PATH_ProtectedJoin( char *root, char *spec )
 
   Function     : PATH_ProtectedJoin
   Description  : Joins the directory with the file specified
   Input        : char *root - directory
                  char *spec - file
   Output       : void
   Returns      : char * - string with joined contents or NULL if
                  the resultant path exists above the root
   Comments     : The returned value must be freed