X11workbench Toolkit  1.0
File I/O 'helper' functions

Functions

size_t WBReadFileIntoBuffer (const char *szFileName, char **ppBuf)
 read a file's contents into a buffer, returning the length of the buffer More...
 
int WBWriteFileFromBuffer (const char *szFileName, const char *pBuf, size_t cbBuf)
 read a file's contents into a buffer, returning the length of the buffer More...
 
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...
 
unsigned long long WBGetFileModDateTime (const char *szFileName)
 Obtain the 'time_t' value for a file's modification date/time (unix time, seconds since the epoch) More...
 
int WBCheckFileModDateTime (const char *szFileName, unsigned long long tVal)
 Compare a 64-bit unsigned integer value against a file's modification date/time (unix time, seconds since the epoch) 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.
header file: file_help.h

Function Documentation

◆ WBAllocDirectoryList()

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 \n

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 '*'.

header file: file_help.h

Definition at line 1187 of file file_help.c.

◆ WBCheckFileModDateTime()

int WBCheckFileModDateTime ( const char *  szFileName,
unsigned long long  tVal 
)

Compare a 64-bit unsigned integer value against a file's modification date/time (unix time, seconds since the epoch)

Parameters
szFileNameA pointer to the file name (must be fully qualified or relative to the current directory)
tValAn unsigned 64-bit integer value representing the file's previous modification date/time value
Returns
An integer value indicating the comparison result of 'tVal' vs the current modification date/time of the file.

Use this function to compare a previously obtained modification date/time value (via 'WBGetFileModDateTime()') against the current value, which is obtained internally by calling the same function.

This is mostly a convenience function, to make checking mod times look a lot cleaner in the code.

header file: file_help.h

Definition at line 1635 of file file_help.c.

◆ WBDestroyDirectoryList()

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()

header file: file_help.h

Definition at line 1362 of file file_help.c.

◆ WBGetCanonicalPath()

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()

header file: file_help.h

Definition at line 803 of file file_help.c.

◆ WBGetCurrentDirectory()

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()

header file: file_help.h

Definition at line 746 of file file_help.c.

◆ WBGetDirectoryListFileFullPath()

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()

header file: file_help.h

Definition at line 1491 of file file_help.c.

◆ WBGetDirectoryListFileStat()

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)

header file: file_help.h

Definition at line 1589 of file file_help.c.

◆ WBGetDirectoryListSymLinkTarget()

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()

header file: file_help.h

Definition at line 1557 of file file_help.c.

◆ WBGetFileModDateTime()

unsigned long long WBGetFileModDateTime ( const char *  szFileName)

Obtain the 'time_t' value for a file's modification date/time (unix time, seconds since the epoch)

Parameters
szFileNameA pointer to the file name (must be fully qualified or relative to the current directory)
Returns
A 64-bit unsigned integer value indicating the file's date/time as a UNIX integer time_t value.

Use this function to obtain the modification date/time of a file. useful to check if it was modified outside of the current process, or by something else within the process.

header file: file_help.h

Definition at line 1609 of file file_help.c.

◆ WBGetSymLinkTarget()

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()

header file: file_help.h

Definition at line 1538 of file file_help.c.

◆ WBIsDirectory()

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.

header file: file_help.h

Definition at line 776 of file file_help.c.

◆ WBNextDirectoryEntry()

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()

header file: file_help.h

Definition at line 1390 of file file_help.c.

◆ WBReadFileIntoBuffer()

size_t WBReadFileIntoBuffer ( const char *  szFileName,
char **  ppBuf 
)

read a file's contents into a buffer, returning the length of the buffer

Parameters
szFileNameA const pointer to a string containing the file name
ppBufA pointer to a 'char *' buffer that is allocated via WBAlloc() and returned by the function
Returns
a positive value on success indicating the length of the data in the returned buffer, or negative on error. A return value of zero indicates an empty file.

Use this function to read the entire contents of a file into a memory buffer.

header file: file_help.h

Definition at line 572 of file file_help.c.

◆ WBReplicateFilePermissions()

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'.

header file: file_help.h

Definition at line 713 of file file_help.c.

◆ WBStat()

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

header file: file_help.h

Definition at line 1574 of file file_help.c.

◆ WBWriteFileFromBuffer()

int WBWriteFileFromBuffer ( const char *  szFileName,
const char *  pBuf,
size_t  cbBuf 
)

read a file's contents into a buffer, returning the length of the buffer

Parameters
szFileNameA const pointer to a string containing the file name
pBufA const pointer to a buffer that contains the data to write
cbBufThe length of data to write to the file.
Returns
a value of zero on success, or non-zero on error (the actual error should be in 'errno')

Use this function to write the entire contents of a buffer to a file. The file will be overwritten if it already exists.

header file: file_help.h

Definition at line 653 of file file_help.c.