File Utilities

Topics:

Overview
Conditional Directives
Constants
Enumerations
Data Structures
Functions

Overview

The file utilities are a collection of data structures and standalone functions used to perform general-purpose platform independent file and directory functions.

Conditional Directives

The following conditional directives are used to define non-portable file and directory routines that need to be ported between UNIX and WIN32 platforms.

__UNIX__ - Directive used for all UNIX compilers

__WIN32__ - Directive used for all WIN32 compilers

Constants

Platform independent path and directory length constants.

const unsigned futils_MAX_LINE_LENGTH = 1024; // Max line length
const unsigned futils_MAX_NAME_LENGTH = 255;  // Max length of a file name
const unsigned futils_MAX_DIR_LENGTH  = 1024; // Max length of a directory name
const unsigned futils_MAX_PATH_LENGTH = 1024; // Max absolute or relative path

Enumerations

typedef enum { 
  // Permission mode enumeration needed to set file permissions
  // when new files are created. 
  futils_READONLY,
  futils_WRITEONLY,
  futils_READWRITE
} futilPermissionMode;

Data Structures

POSIX style directory entry for WIN32 platforms.

typedef struct dirent {
  HANDLE d_ino;   // File number of entry 
  DWORD d_reclen; // Length of this record 
  DWORD d_namlen; // Length of string in d_name 
  char  d_name[futils_MAX_NAME_LENGTH]; // Name of this file 

  // WIN32 Specifics 
  WIN32_FIND_DATA file; // Describes a file found by a WIN32 find function 
} WIN32FileData;

POSIX style directory structure for WIN32 platforms.

typedef struct {
  int dd_fd;            // optional file descriptor 
  DWORD dd_loc;         // file location in the directory stream 
  DWORD dd_size;        // file size  
  WIN32FileData dd_buf; // WIN32 file information 
  char dd_dirname[futils_MAX_NAME_LENGTH]; // Directory name 
} DIR;

Functions

File and Directory Functions:
futils_chdir()
futils_chmod()
futils_filelength()
futils_exists()
futils_genoutputfilename()
futils_getcwd()
futils_hasdriveletter()
futils_isdirectory()
futils_isfile()
futils_makeDOSpath()
futils_makeUNIXpath()
futils_mkdir()
futils_pathsimplify()
futils_remove()
futils_rename()
futils_rmdir()

Directory Stream Functions:
futils_closedir()
futils_opendir()
futils_readdir()
futils_rewinddir()

int futils_chdir(const char *dir_name) - Standalone function used to change directories. Returns zero if successful.

int futils_chmod(const char *fname, futilPermissionMode pmode) - Standalone function used to change the file-permission settings. The "pmode" variable should be equal to futils_READONLY, futils_WRITEONLY, or futils_READWRITE. Returns a non-zero value if an error occurs.

int futils_exists(const char *name) - Standalone function that tests to see if the specified directory or file name exists. Returns true if the file or directory exists.

long futils_filelength(int fd) - Standalone function that returns the file size, in bytes, for the specified file descriptor. Return a value of -1 to indicate an error.

int futils_genoutputfilename(const char *current_file, char *out_file,char *extension) - Standalone function used to generate a name for the output file using the "current_file" name with the specified dot extension. NOTE: This function assumes that the necessary memory has already been allocated for the "out_file" variable by the calling function. Returns a non-zero value if any errors occur.

int futils_getcwd(char *dir, unsigned max_len) - Standalone function that passes back the present working directory in the "dir" variable. Returns 0 if no errors occur. NOTE: This function assumes that the required amount of memory has already been allocated for the "dir" pointer. The "max_len" value must be at least one byte greater than the length of the pathname to be returned.

int futils_hasdriveletter(const char *dir_name, char *letter) - WIN32 function used to parse the drive letter from the specified directory. Returns false if the path does not contain a drive letter. If a drive letter is found it will be passed back in the "letter" variable.

int futils_isdirectory(const char *dir_name) - Standalone function that returns true if the specified name is a directory.

int futils_isfile(const char *fname) - Standalone function that returns true if the specified name is any kind of file or false if this is a directory.

void futils_makeDOSpath(char *path) - Standalone function used to make a DOS directory path by changing all forward slash path separators to back slashes.

void futils_makeUNIXpath(char *path) - Standalone function used to make a UNIX directory path by changing all back slash path separators to forward slashes.

int futils_mkdir(const char *dir_name) - Standalone function used to make the specified directory (with sub-directories) if the directory does not exist. Returns a non-zero value if an error occurs. UNIX file systems will use 755 permissions when new directories are created.

void futils_pathsimplify(const char *path, char *new_path, char path_sep) - Standalone function used to simplify a path and return a new path. The path separator should either be a forward slash for UNIX file systems or a backslash for DOS/WIN32 file systems. Multiple path separators will be collapsed to a single path separator. Leading `./' paths and trailing `/.' paths will be removed. Trailing path separators will be removed. All non-leading `../' paths and trailing `..' paths are handled by removing portions of the path. NOTE: This function assumes that the necessary memory has already been allocated for the "new_path" variable by the calling function.

int futils_remove(const char *fname) - Standalone function used to remove the specified file. Returns zero if successful.

int futils_rename(const char *oldname, const char *newname) - Standalone function used to rename the specified file. Returns zero if successful.

int futils_rmdir(const char *dir_name) - Standalone function used to remove the specified directory. Returns zero if successful. The directory must be empty and not be the current working directory or the root directory

int futils_closedir(DIR *dirp) - Standalone function used to close the directory stream referred to by the "dirp" argument. Returns zero upon successful completion or -1 if an error occurs.

DIR *futils_opendir(const char *dirname) - Standalone function used to open a directory stream corresponding to the directory named by the "dirname" argument. The directory stream is positioned at the first entry.

struct dirent *futils_readdir(DIR *dirp) - Standalone function that returns a pointer to a structure representing the directory entry at the current position in the directory stream specified by the "dirp" argument, and positions the directory stream at the next entry. It returns a null pointer upon reaching the end of the directory stream.

void futils_rewinddir(DIR *dirp) - Standalone function used to reset the position of the directory stream to which "dirp" refers to the beginning of the directory.