X11 Work Bench Toolkit  1.0
File I/O 'helper' functions

Functions

int WBReplicateFilePermissions (const char *szProto, const char *szTarget)
 replicate permissions on a target file based on another file's permissions More...
 
char * WBGetCurrentDirectory (void)
 Return allocated string containing the current working directory. More...
 
int WBIsDirectory (const char *szName)
 Return whether a file is a directory or a symlink to a directory. More...
 
char * WBGetCanonicalPath (const char *szFileName)
 Return the canonical path for a file name (similar to POSIX 'realpath()' funtion) More...
 
void * WBAllocDirectoryList (const char *szDirSpec)
 Allocate a 'Directory List' object for a specified directory spec. More...
 
void WBDestroyDirectoryList (void *pDirectoryList)
 Destroy a 'Directory List' object allocated by WBAllocDirectoryList() More...
 
int WBNextDirectoryEntry (void *pDirectoryList, char *szNameReturn, int cbNameReturn, unsigned long *pdwModeAttrReturn)
 Obtain information about the next entry in a 'Directory List'. More...
 
char * WBGetDirectoryListFileFullPath (const void *pDirectoryList, const char *szFileName)
 Construct a fully qualified canonical path from a 'Directory List' object and a file name. More...
 
char * WBGetSymLinkTarget (const char *szFileName)
 Obtain the target of a symbolic link. More...
 
char * WBGetDirectoryListSymLinkTarget (const void *pDirectoryList, const char *szFileName)
 Obtain the target of a symbolic link file name with respect to a 'Directory List' object. More...
 
int WBStat (const char *szFileName, unsigned long *pdwModeAttrReturn)
 Obtain the 'stat' flags for a file name, resolving links as needed. More...
 
int WBGetDirectoryListFileStat (const void *pDirectoryList, const char *szFileName, unsigned long *pdwModeAttrReturn)
 Obtain the 'stat' flags for a file name, resolving links as needed, with respect to a 'Directory List' object. More...
 

Detailed Description

Utility functions and structures associated with files, file info and directory searching

File helper utilities that enable you to more easily enumerate the contents of a directory, make a backup copy of an existing file, get a file's type or permissions, or canonicalize a file name.

Function Documentation

void* WBAllocDirectoryList ( const char *  szDirSpec)

Allocate a 'Directory List' object for a specified directory spec.

Parameters
szDirSpecThe directory specification, using standard wildcard specifiers on the file spec only
Returns
A pointer to a 'Directory List' object, or NULL on error

Use this function to list a directory by creating a 'Directory List' object and then subsequently passing it to 'WBNextDirectoryEntry' to obtain information about each entry in the directory. This function does NOT return '.' or '..' as valid file names.

The pointer returned by this function must be destroyed using WBDestroyDirectoryList()

NOTE: you may not specify a wildcard within a directory name unless it is the the specification for the file name that you are searching for within its parent directory. The directory name must also exist or the function will return a NULL (error). If the specified path name ends in a '/' the file spec will be assumed to be '*'.

Definition at line 1046 of file file_help.c.

void WBDestroyDirectoryList ( void *  pDirectoryList)

Destroy a 'Directory List' object allocated by WBAllocDirectoryList()

Parameters
pDirectoryListA pointer to a 'Directory List' object allocated by WBAllocDirectoryList()

Use this function to destroy a 'Directory List' object allocated by WBAllocDirectoryList()

Definition at line 1221 of file file_help.c.

char* WBGetCanonicalPath ( const char *  szFileName)

Return the canonical path for a file name (similar to POSIX 'realpath()' funtion)

Parameters
szFileNameThe file name to query. If the name contains symbolic links, they will be resolved.
Returns
A WBAlloc'd buffer containing the canonical path, or NULL on error.

Use this function to determine the canonical name for a specified path. If the path does not exist, those elements of the path that DO exist will be resolved, and the remaining parts of the name will be added to form the canonical path. If an element of the specified directory name is NOT actually a directory (or a symlink to a directory), the function will return NULL indicating an error.

The caller must free any non-NULL return values using WBFree()

Definition at line 662 of file file_help.c.

char* WBGetCurrentDirectory ( void  )

Return allocated string containing the current working directory.

Returns
valid pointer or NULL on error

A convenience function that wraps the 'getcwd()' API and returns a 'WBAlloc'd pointer to a string. The caller must free any non-NULL return values using WBFree()

Definition at line 605 of file file_help.c.

char* WBGetDirectoryListFileFullPath ( const void *  pDirectoryList,
const char *  szFileName 
)

Construct a fully qualified canonical path from a 'Directory List' object and a file name.

Parameters
pDirectoryListA pointer to a 'Directory List' object. May be NULL.
szFileNameA pointer to a file within the directory. This file does not need to exist.
Returns
A 'WBAlloc'd buffer containing the fully qualified file name as an ASCII string.

Use this function to get a canonical file name for a file within a directory listing.

The caller must free any non-NULL return values using WBFree()

Definition at line 1350 of file file_help.c.

int WBGetDirectoryListFileStat ( const void *  pDirectoryList,
const char *  szFileName,
unsigned long *  pdwModeAttrReturn 
)

Obtain the 'stat' flags for a file name, resolving links as needed, with respect to a 'Directory List' object.

Parameters
pDirectoryListA pointer to a 'Directory List' object. May be NULL.
szFileNameA pointer to the file name of the symbolic link
pdwModeAttrReturnA pointer to the unsigned long integer that receives the 'stat' flags
Returns
A zero value if successful, non-zero otherwise (same return as 'stat()')

Use this function to retrieve flags for a regular file, directory, or the target of a symbolic link with respect to a 'Directory List' object (for relative paths)

Definition at line 1448 of file file_help.c.

char* WBGetDirectoryListSymLinkTarget ( const void *  pDirectoryList,
const char *  szFileName 
)

Obtain the target of a symbolic link file name with respect to a 'Directory List' object.

Parameters
pDirectoryListA pointer to a 'Directory List' object. May be NULL.
szFileNameA pointer to the file name of the symbolic link
Returns
A 'WBAlloc'd buffer containing the unmodified link target path as an ASCII string

Use this function to retrieve a symbolic link's target file name with respect to a 'Directory List' object (for relative paths). The link target is unmodified, and may be a relative path. For a canonical equivalent, use WBGetCanonicalPath()

The caller must free any non-NULL return values using WBFree()

Definition at line 1416 of file file_help.c.

char* WBGetSymLinkTarget ( const char *  szFileName)

Obtain the target of a symbolic link.

Parameters
szFileNameA pointer to the file name of the symbolic link
Returns
A 'WBAlloc'd buffer containing the link target path as an ASCII string (unaltered)

Use this function to retrieve a symbolic link's target file name. May be a relative path. For a canonical equivalent, use WBGetCanonicalPath()

The caller must free any non-NULL return values using WBFree()

Definition at line 1397 of file file_help.c.

int WBIsDirectory ( const char *  szName)

Return whether a file is a directory or a symlink to a directory.

Parameters
szNameThe file name to query. Can be a symbolic link. The name [and target path for a symlink] must exist.
Returns
non-zero if the file is (or the symlink points to) a directory, 0 otherwise

Use this function to determine if the specified file is a directory, or is a symbolic link that points to a directory.

Definition at line 635 of file file_help.c.

int WBNextDirectoryEntry ( void *  pDirectoryList,
char *  szNameReturn,
int  cbNameReturn,
unsigned long *  pdwModeAttrReturn 
)

Obtain information about the next entry in a 'Directory List'.

Parameters
pDirectoryListA pointer to the 'Directory List' object
szNameReturnA pointer to a buffer that receives the file name
cbNameReturnThe size of the 'szNameReturn' buffer (in bytes)
pdwModeAttrReturnA pointer to an unsigned long integer that receives the mode/attribute bits
Returns
An integer value < 0 on error, > 0 on EOF, or 0 if a matching entry was found

Use this function to get the next file name from the contents of a directory listing that is specified by a 'Directory List' object created by WBAllocDirectoryList()

Definition at line 1249 of file file_help.c.

int WBReplicateFilePermissions ( const char *  szProto,
const char *  szTarget 
)

replicate permissions on a target file based on another file's permissions

Parameters
szProtoThe file to be used as a permission 'prototype'. If it represents a symbolic link, the file that the link points to will be used.
szTargetThe target file. If it represents a symbolic link, the link itself will be used.
Returns
non-zero on error, zero on success

Use this function to replicate the permissions of one file onto another. Useful when making a backup of an original file, and/or creating a new file with the same name/characteristics as the old file, but not necessarily 'written in place'.

Definition at line 572 of file file_help.c.

int WBStat ( const char *  szFileName,
unsigned long *  pdwModeAttrReturn 
)

Obtain the 'stat' flags for a file name, resolving links as needed.

Parameters
szFileNameA pointer to the file name of the symbolic link
pdwModeAttrReturnA pointer to the unsigned long integer that receives the 'stat' flags
Returns
A zero value if successful, non-zero otherwise (same return as 'stat()')

Use this function to retrieve flags for a regular file, directory, or the target of a symbolic link

Definition at line 1433 of file file_help.c.