250 рядки
11 KiB
C
250 рядки
11 KiB
C
|
|
//( { file_desc:"A collection of file system utility functions." kw:[system file]}
|
|
//
|
|
// Note that cmFileSysInitialize() creates an internal cmLHeapH_t based
|
|
// heap manager from which it allocates memory for some returned objects.
|
|
// (e.g. cmFileSysMakeFn(), cmFileSysPathParts(), cmFileSysDirEntries())
|
|
// Where possible the client can explicitely free these objects via the
|
|
// provided functions. (e.g. cmFileSysFreeFn(), cmFileSysFreePathParts(), cmFileSysDirFreeEntries())
|
|
// However if these objects are not free they will be automatically deallocated
|
|
// when the internal heap is destroyed by cmFileSysFinalize().
|
|
//
|
|
//)
|
|
|
|
#ifndef cmFileSys_h
|
|
#define cmFileSys_h
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
//(
|
|
// Result codes returned by cmFileSys.h functions
|
|
enum
|
|
{
|
|
kOkFsRC = cmOkRC,
|
|
kMemAllocErrFsRC,
|
|
kLHeapAllocErrFsRC,
|
|
kStatFailFsRC,
|
|
kAssertFailFsRC,
|
|
kOpenDirFailFsRC,
|
|
kFnTooLongFsRC,
|
|
kMkDirFailFsRC,
|
|
kSysErrFsRC,
|
|
kOsxFailFsRC,
|
|
kLinuxFailFsRC,
|
|
kInvalidDirFsRC,
|
|
kGenFileFailFsRC,
|
|
kAccessFailFsRC
|
|
};
|
|
|
|
|
|
typedef cmHandle_t cmFileSysH_t; //< Opaque handle type used by all cmFileSys.h functions
|
|
typedef unsigned cmFsRC_t; //< Result code used as the return type by many cmFileSys.h functions.
|
|
|
|
extern cmFileSysH_t cmFileSysNullHandle; // NULL handle to be used for setting cmFileSysH_t type handles to an explicit uninitialized value.
|
|
|
|
// Initialize a file system object.
|
|
// If *hp was not initalized by an earlier call to cmFileSysInitialize() then it should
|
|
// be set to cmFileSysNullHandle prior to calling this function. If *hp is a valid handle
|
|
// then it is automatically finalized by an internal call to cmFileSysFinalize() prior to
|
|
// being re-iniitalized.
|
|
// The appNameStr is used to determine the location of the preference and resource directories
|
|
// on some platforms
|
|
cmFsRC_t cmFileSysInitialize( cmFileSysH_t* hp, cmCtx_t* ctx, const cmChar_t* appNameStr );
|
|
|
|
// Finalize a file system object.
|
|
// Upon successful completion *hp is set to cmFileSysNullHandle.
|
|
cmFsRC_t cmFileSysFinalize( cmFileSysH_t* hp );
|
|
|
|
// Returns true if the file system handle is active and initialized.
|
|
bool cmFileSysIsValid( cmFileSysH_t h );
|
|
|
|
const cmChar_t* cmFileSysAppName( cmFileSysH_t h ); //< Return the application name as passed to cmFileSysInitialize()
|
|
const cmChar_t* cmFileSysPrefsDir( cmFileSysH_t h ); //< Return the operating system dependent preference data directory for this application.
|
|
const cmChar_t* cmFileSysRsrcDir( cmFileSysH_t h ); //< Return the operating system dependent application resource directory for this application.
|
|
const cmChar_t* cmFileSysUserDir( cmFileSysH_t h ); //< Return the operating system dependent user directory for this application.
|
|
|
|
// Check if a request to create a file will succeed.
|
|
bool cmFileSysCanWriteToDir( cmFileSysH_t h, const cmChar_t* dirStr );
|
|
|
|
// Test the type of a file system object:
|
|
//
|
|
bool cmFileSysIsDir( cmFileSysH_t h, const cmChar_t* dirStr ); //< Return true if 'dirStr' refers to an existing directory.
|
|
bool cmFileSysIsFile( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to an existing file.
|
|
bool cmFileSysIsLink( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to a symbolic link.
|
|
|
|
// Create File Names:
|
|
//
|
|
// Create a file name by concatenating sub-strings.
|
|
//
|
|
// Variable arg's. entries are directories inserted between
|
|
// 'dirPrefixStr' and the file name.
|
|
// Terminate var arg's directory list with a NULL.
|
|
//
|
|
// The returned string is allocated in a local heap maintained by the cmFileSys object.
|
|
// The memory used by the string will exist until it is released with cmFileSysFreeFn()
|
|
// or the cmFileSys object is finalized.
|
|
const cmChar_t* cmFileSysMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
|
|
|
|
// Same as cmFileSysMakeFn with but with a va_list argument to accept the var. args. parameters.
|
|
const cmChar_t* cmFileSysVMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
|
|
|
|
// Release the file name created through an earlier call to cmFileSysMakeFn().
|
|
void cmFileSysFreeFn( cmFileSysH_t h, const cmChar_t* fn );
|
|
|
|
// Generate an unused filename in the directory 'dir' beginning with the prefix 'prefixStr'.
|
|
// The returned file name will have the format: <dir>/<prefixStr>nnnn.<extStr> where
|
|
// nnn represents 1 or more digits. The returned string must be released with a
|
|
// call to cmMemFree().
|
|
cmFsRC_t cmFileSysGenFn( cmFileSysH_t h, const cmChar_t* dir, const cmChar_t* prefixStr, const cmChar_t* extStr, const cmChar_t** fnPtr );
|
|
|
|
// Create a directory - where the entire path already exists except for the
|
|
// final directory.
|
|
cmFsRC_t cmFileSysMkDir( cmFileSysH_t h, const cmChar_t* dir );
|
|
|
|
// Create a complete directory path - where any of the path segments may
|
|
// not already exist.
|
|
cmFsRC_t cmFileSysMkDirAll( cmFileSysH_t h, const cmChar_t* dir );
|
|
|
|
// Parse a path into its parts:
|
|
//
|
|
// Return record used by cmFileSysParts()
|
|
typedef struct
|
|
{
|
|
const cmChar_t* dirStr;
|
|
const cmChar_t* fnStr;
|
|
const cmChar_t* extStr;
|
|
} cmFileSysPathPart_t;
|
|
|
|
// Given a file name decompose it into a directory string, file name string and file extension string.
|
|
// The cmFileSysPathPart_t record and the memory used by the strings that it references
|
|
// are allocated from a local heap maintained by the cmFileSys object. This memory will exist
|
|
// until it is released with cmFileSysFreePathParts() or the cmFileSysH_t handle is finalized.
|
|
cmFileSysPathPart_t* cmFileSysPathParts( cmFileSysH_t h, const cmChar_t* pathNameStr );
|
|
|
|
// Free the memory associated with a cmFileSysPathPart_t record returned from an eariler call to cmFileSysPathParts().
|
|
void cmFileSysFreePathParts( cmFileSysH_t h, cmFileSysPathPart_t* p );
|
|
|
|
// Return the parts of a directory path as an array of strings.
|
|
// The last element in the array is set to NULL to mark the end of the array.
|
|
// Note that all '/' separator characters are removed from the result with
|
|
// the exception of the first one - which denotes the root directory.
|
|
// The returned array is allocated from the file systems internal heap and will
|
|
// be automatically released when the file system is closed by cmFileSysDestroy().
|
|
// The caller may optionally release the array memory with a call to
|
|
// cmFileSysFreeDirParts().
|
|
cmChar_t** cmFileSysDirParts( cmFileSysH_t h, const cmChar_t* dirStr );
|
|
void cmFileSysFreeDirParts( cmFileSysH_t h, cmChar_t** dirStrArray );
|
|
|
|
// Return the count of elements in a directory parts array as returned by
|
|
// cmFileSysDirParts().
|
|
unsigned cmFileSysDirPartsCount(cmFileSysH_t h, cmChar_t** dirStrArray );
|
|
|
|
// Form a directory string from a NULL terminated array of strings.
|
|
// If the first element in the array is set to '/' then the
|
|
// resulting directory will be absolute rather than relative.
|
|
// The returned string is allocated from the file systems internal heap and will
|
|
// be automatically released when the file system is closed by cmFileSysDestroy().
|
|
// The caller may optionally release the array memory with a call to
|
|
// cmFileSysFreeDir().
|
|
cmChar_t* cmFileSysFormDir( cmFileSysH_t h, cmChar_t** dirStrArray, unsigned n );
|
|
void cmFileSysFreeDir( cmFileSysH_t h, const cmChar_t* dir );
|
|
|
|
// Walk a directory tree:
|
|
//
|
|
// Flags used by cmFileSysDirEntries 'includeFlags' parameter.
|
|
enum
|
|
{
|
|
kFileFsFl = 0x001, //< include all visible files
|
|
kDirFsFl = 0x002, //< include all visible directory
|
|
kLinkFsFl = 0x004, //< include all symbolic links
|
|
kInvisibleFsFl = 0x008, //< include file/dir name beginning with a '.'
|
|
kCurDirFsFl = 0x010, //< include '.' directory
|
|
kParentDirFsFl = 0x020, //< include '..' directory
|
|
|
|
kAllFsFl = 0x02f, //< all type flags
|
|
|
|
kFullPathFsFl = 0x040, //< return the full path in the 'name' field of cmFileSysDirEntry_t;
|
|
kRecurseFsFl = 0x080, //< recurse into directories
|
|
kRecurseLinksFsFl = 0x100 //< recurse into symbol link directories
|
|
|
|
};
|
|
|
|
// The return type for cmFileSysDirEntries().
|
|
typedef struct
|
|
{
|
|
unsigned flags; //< Entry type flags from kXXXFsFl.
|
|
const cmChar_t* name; //< Entry name or full path depending on kFullPathFsFl.
|
|
} cmFileSysDirEntry_t;
|
|
|
|
// Return the file and directory names contained in a given subdirectory.
|
|
//
|
|
// Set 'includeFlags' with the kXXXFsFl flags of the files to include in the returned
|
|
// directory entry array. The value pointed to by dirEntryCntPtr will be set to the
|
|
// number of records in the returned array.
|
|
cmFileSysDirEntry_t* cmFileSysDirEntries( cmFileSysH_t h, const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
|
|
|
|
// Release the memory assoicated with a cmFileSysDirEntry_t array returned from an earlier call to cmFileSysDirEntries().
|
|
void cmFileSysDirFreeEntries( cmFileSysH_t h, cmFileSysDirEntry_t* p );
|
|
|
|
|
|
// Return the last error code generated by the file system.
|
|
cmFsRC_t cmFileSysErrorCode( cmFileSysH_t h );
|
|
|
|
//-------------------------------------------------------------------------------------------------
|
|
|
|
// Global file system functions:
|
|
// These functions work using a global cmFileSysH created by cmFsInitialize().
|
|
// The functions are otherwise just wrappers for the same named function above.
|
|
|
|
cmFsRC_t cmFsInitialize( cmCtx_t* ctx, const cmChar_t* appNameStr );
|
|
cmFsRC_t cmFsFinalize();
|
|
|
|
const cmChar_t* cmFsAppName();
|
|
const cmChar_t* cmFsPrefsDir();
|
|
const cmChar_t* cmFsRsrcDir();
|
|
const cmChar_t* cmFsUserDir();
|
|
|
|
bool cmFsCanWriteToDir( const cmChar_t* dirStr );
|
|
|
|
bool cmFsIsDir( const cmChar_t* dirStr );
|
|
bool cmFsIsFile( const cmChar_t* fnStr );
|
|
bool cmFsIsLink( const cmChar_t* fnStr );
|
|
|
|
const cmChar_t* cmFsVMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
|
|
const cmChar_t* cmFsMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
|
|
void cmFsFreeFn( const cmChar_t* fn );
|
|
cmFsRC_t cmFsGenFn( const cmChar_t* dir, const cmChar_t* prefixStr, const cmChar_t* extStr, const cmChar_t** fnPtr );
|
|
|
|
|
|
cmFsRC_t cmFsMkDir( const cmChar_t* dir );
|
|
cmFsRC_t cmFsMkDirAll( const cmChar_t* dir );
|
|
|
|
cmFileSysPathPart_t* cmFsPathParts( const cmChar_t* pathNameStr );
|
|
void cmFsFreePathParts( cmFileSysPathPart_t* p );
|
|
|
|
|
|
cmChar_t** cmFsDirParts( const cmChar_t* dirStr );
|
|
void cmFsFreeDirParts( cmChar_t** dirStrArray );
|
|
unsigned cmFsDirPartsCount( cmChar_t** dirStrArray );
|
|
cmChar_t* cmFsFormDir( cmChar_t** dirStrArray, unsigned n );
|
|
void cmFsFreeDir( const cmChar_t* dir );
|
|
|
|
cmFileSysDirEntry_t* cmFsDirEntries( const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
|
|
void cmFsDirFreeEntries( cmFileSysDirEntry_t* p );
|
|
|
|
cmFsRC_t cmFsErrorCode();
|
|
|
|
|
|
// Test and example function to demonstrate the use of the functions in cmFileSys.h
|
|
cmFsRC_t cmFileSysTest( cmCtx_t* ctx );
|
|
|
|
//)
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|