libcm is a C development framework with an emphasis on audio signal processing applications.
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

cmFileSys.h 14KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290
  1. //( { file_desc:"A collection of file system utility functions." kw:[system file]}
  2. //
  3. // Note that cmFileSysInitialize() creates an internal cmLHeapH_t based
  4. // heap manager from which it allocates memory for some returned objects.
  5. // (e.g. cmFileSysMakeFn(), cmFileSysPathParts(), cmFileSysDirEntries())
  6. // Where possible the client can explicitely free these objects via the
  7. // provided functions. (e.g. cmFileSysFreeFn(), cmFileSysFreePathParts(), cmFileSysDirFreeEntries())
  8. // However if these objects are not free they will be automatically deallocated
  9. // when the internal heap is destroyed by cmFileSysFinalize().
  10. //
  11. //)
  12. #ifndef cmFileSys_h
  13. #define cmFileSys_h
  14. #ifdef __cplusplus
  15. extern "C" {
  16. #endif
  17. //(
  18. // Result codes returned by cmFileSys.h functions
  19. enum
  20. {
  21. kOkFsRC = cmOkRC,
  22. kMemAllocErrFsRC,
  23. kLHeapAllocErrFsRC,
  24. kStatFailFsRC,
  25. kAssertFailFsRC,
  26. kOpenDirFailFsRC,
  27. kFnTooLongFsRC,
  28. kMkDirFailFsRC,
  29. kSysErrFsRC,
  30. kOsxFailFsRC,
  31. kLinuxFailFsRC,
  32. kInvalidDirFsRC,
  33. kGenFileFailFsRC,
  34. kAccessFailFsRC,
  35. kFormFnFailFsRC
  36. };
  37. typedef cmHandle_t cmFileSysH_t; //< Opaque handle type used by all cmFileSys.h functions
  38. typedef unsigned cmFsRC_t; //< Result code used as the return type by many cmFileSys.h functions.
  39. extern cmFileSysH_t cmFileSysNullHandle; // NULL handle to be used for setting cmFileSysH_t type handles to an explicit uninitialized value.
  40. // Initialize a file system object.
  41. // If *hp was not initalized by an earlier call to cmFileSysInitialize() then it should
  42. // be set to cmFileSysNullHandle prior to calling this function. If *hp is a valid handle
  43. // then it is automatically finalized by an internal call to cmFileSysFinalize() prior to
  44. // being re-iniitalized.
  45. // The appNameStr is used to determine the location of the preference and resource directories
  46. // on some platforms
  47. cmFsRC_t cmFileSysInitialize( cmFileSysH_t* hp, cmCtx_t* ctx, const cmChar_t* appNameStr );
  48. // Finalize a file system object.
  49. // Upon successful completion *hp is set to cmFileSysNullHandle.
  50. cmFsRC_t cmFileSysFinalize( cmFileSysH_t* hp );
  51. // Returns true if the file system handle is active and initialized.
  52. bool cmFileSysIsValid( cmFileSysH_t h );
  53. const cmChar_t* cmFileSysAppName( cmFileSysH_t h ); //< Return the application name as passed to cmFileSysInitialize()
  54. const cmChar_t* cmFileSysPrefsDir( cmFileSysH_t h ); //< Return the operating system dependent preference data directory for this application.
  55. const cmChar_t* cmFileSysRsrcDir( cmFileSysH_t h ); //< Return the operating system dependent application resource directory for this application.
  56. const cmChar_t* cmFileSysUserDir( cmFileSysH_t h ); //< Return the operating system dependent user directory for this application.
  57. // Check if a request to create a file will succeed.
  58. bool cmFileSysCanWriteToDir( cmFileSysH_t h, const cmChar_t* dirStr );
  59. // Test the type of a file system object:
  60. //
  61. bool cmFileSysIsDir( cmFileSysH_t h, const cmChar_t* dirStr ); //< Return true if 'dirStr' refers to an existing directory.
  62. bool cmFileSysIsFile( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to an existing file.
  63. bool cmFileSysIsLink( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to a symbolic link.
  64. // Create File Names:
  65. //
  66. // Create a file name by concatenating sub-strings.
  67. //
  68. // Variable arg's. entries are directories inserted between
  69. // 'dirPrefixStr' and the file name.
  70. // Terminate var arg's directory list with a NULL.
  71. //
  72. // The returned string is allocated in a local heap maintained by the cmFileSys object.
  73. // The memory used by the string will exist until it is released with cmFileSysFreeFn()
  74. // or the cmFileSys object is finalized.
  75. const cmChar_t* cmFileSysMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  76. // Same as cmFileSysMakeFn but prefixes the entire file path with the current users
  77. // home directory. (i.e. /home/me/<dirPrefix>/<var-args-dir-0>/<var-args-dir1>/<fn>.<ext>)
  78. const cmChar_t* cmFileSysMakeUserFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  79. // Same as cmFileSysMakeFn but with a va_list argument to accept the var. args. parameters.
  80. const cmChar_t* cmFileSysVMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  81. // Same as cmFileSysMakeUserFn but with a va_list argument to accept the var. args parameters.
  82. const cmChar_t* cmFileSysVMakeUserFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  83. // Equivalent to same named cmFileSysMakeFn() functions but form a directory
  84. // path rather than a file name path.
  85. const cmChar_t* cmFileSysVMakeDir( cmFileSysH_t h, const cmChar_t* dir, va_list vl );
  86. const cmChar_t* cmFileSysMakeDir( cmFileSysH_t h, const cmChar_t* dir, ... );
  87. const cmChar_t* cmFileSysVMakeUserDir( cmFileSysH_t h, const cmChar_t* dir, va_list vl );
  88. const cmChar_t* cmFileSysMakeUserDir( cmFileSysH_t h, const cmChar_t* dir, ... );
  89. // Equivalent to same named cmFileSysMake() functions but assumes a single directory prefix and the file name
  90. // extension is attached to 'fn'.
  91. const cmChar_t* cmFileSysMakeDirFn( cmFileSysH_t h, const cmChar_t* dir, const cmChar_t* fn );
  92. // Same as cmFileSysMakeDirFn() but prefixes 'dir' with the users home directory.
  93. const cmChar_t* cmFileSysMakeUserDirFn(cmFileSysH_t h, const cmChar_t* dir, const cmChar_t* fn );
  94. // Release the file name created through an earlier call to cmFileSysMakeFn().
  95. void cmFileSysFreeFn( cmFileSysH_t h, const cmChar_t* fn );
  96. // Generate an unused filename in the directory 'dir' beginning with the prefix 'prefixStr'.
  97. // The returned file name will have the format: <dir>/<prefixStr>nnnn.<extStr> where
  98. // nnn represents 1 or more digits. The returned string must be released with a
  99. // call to cmMemFree().
  100. cmFsRC_t cmFileSysGenFn( cmFileSysH_t h, const cmChar_t* dir, const cmChar_t* prefixStr, const cmChar_t* extStr, const cmChar_t** fnPtr );
  101. // Create a directory - where the entire path already exists except for the
  102. // final directory.
  103. cmFsRC_t cmFileSysMkDir( cmFileSysH_t h, const cmChar_t* dir );
  104. // Same as cmFileSysMkDir() but 'dir' is automatically prefixed with the users home directory.
  105. cmFsRC_t cmFileSysMkUserDir( cmFileSysH_t h, const cmChar_t* dir );
  106. // Create a complete directory path - where any of the path segments may
  107. // not already exist.
  108. cmFsRC_t cmFileSysMkDirAll( cmFileSysH_t h, const cmChar_t* dir );
  109. // Same as cmFileSysMkDir() but 'dir' is automatically prefixed with the users home directory.
  110. cmFsRC_t cmFileSysMkUserDirAll( cmFileSysH_t h, const cmChar_t* dir );
  111. // Parse a path into its parts:
  112. //
  113. // Return record used by cmFileSysParts()
  114. typedef struct
  115. {
  116. const cmChar_t* dirStr;
  117. const cmChar_t* fnStr;
  118. const cmChar_t* extStr;
  119. } cmFileSysPathPart_t;
  120. // Given a file name decompose it into a directory string, file name string and file extension string.
  121. // The cmFileSysPathPart_t record and the memory used by the strings that it references
  122. // are allocated from a local heap maintained by the cmFileSys object. This memory will exist
  123. // until it is released with cmFileSysFreePathParts() or the cmFileSysH_t handle is finalized.
  124. cmFileSysPathPart_t* cmFileSysPathParts( cmFileSysH_t h, const cmChar_t* pathNameStr );
  125. // Free the memory associated with a cmFileSysPathPart_t record returned from an eariler call to cmFileSysPathParts().
  126. void cmFileSysFreePathParts( cmFileSysH_t h, cmFileSysPathPart_t* p );
  127. // Return the parts of a directory path as an array of strings.
  128. // The last element in the array is set to NULL to mark the end of the array.
  129. // Note that all '/' separator characters are removed from the result with
  130. // the exception of the first one - which denotes the root directory.
  131. // The returned array is allocated from the file systems internal heap and will
  132. // be automatically released when the file system is closed by cmFileSysDestroy().
  133. // The caller may optionally release the array memory with a call to
  134. // cmFileSysFreeDirParts().
  135. cmChar_t** cmFileSysDirParts( cmFileSysH_t h, const cmChar_t* dirStr );
  136. void cmFileSysFreeDirParts( cmFileSysH_t h, cmChar_t** dirStrArray );
  137. // Return the count of elements in a directory parts array as returned by
  138. // cmFileSysDirParts().
  139. unsigned cmFileSysDirPartsCount(cmFileSysH_t h, cmChar_t** dirStrArray );
  140. // Form a directory string from a NULL terminated array of strings.
  141. // If the first element in the array is set to '/' then the
  142. // resulting directory will be absolute rather than relative.
  143. // The returned string is allocated from the file systems internal heap and will
  144. // be automatically released when the file system is closed by cmFileSysDestroy().
  145. // The caller may optionally release the array memory with a call to
  146. // cmFileSysFreeDir().
  147. cmChar_t* cmFileSysFormDir( cmFileSysH_t h, cmChar_t** dirStrArray, unsigned n );
  148. void cmFileSysFreeDir( cmFileSysH_t h, const cmChar_t* dir );
  149. // Walk a directory tree:
  150. //
  151. // Flags used by cmFileSysDirEntries 'includeFlags' parameter.
  152. enum
  153. {
  154. kFileFsFl = 0x001, //< include all visible files
  155. kDirFsFl = 0x002, //< include all visible directory
  156. kLinkFsFl = 0x004, //< include all symbolic links
  157. kInvisibleFsFl = 0x008, //< include file/dir name beginning with a '.'
  158. kCurDirFsFl = 0x010, //< include '.' directory
  159. kParentDirFsFl = 0x020, //< include '..' directory
  160. kAllFsFl = 0x02f, //< all type flags
  161. kFullPathFsFl = 0x040, //< return the full path in the 'name' field of cmFileSysDirEntry_t;
  162. kRecurseFsFl = 0x080, //< recurse into directories
  163. kRecurseLinksFsFl = 0x100 //< recurse into symbol link directories
  164. };
  165. // The return type for cmFileSysDirEntries().
  166. typedef struct
  167. {
  168. unsigned flags; //< Entry type flags from kXXXFsFl.
  169. const cmChar_t* name; //< Entry name or full path depending on kFullPathFsFl.
  170. } cmFileSysDirEntry_t;
  171. // Return the file and directory names contained in a given subdirectory.
  172. //
  173. // Set 'includeFlags' with the kXXXFsFl flags of the files to include in the returned
  174. // directory entry array. The value pointed to by dirEntryCntPtr will be set to the
  175. // number of records in the returned array.
  176. cmFileSysDirEntry_t* cmFileSysDirEntries( cmFileSysH_t h, const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
  177. // Release the memory assoicated with a cmFileSysDirEntry_t array returned from an earlier call to cmFileSysDirEntries().
  178. void cmFileSysDirFreeEntries( cmFileSysH_t h, cmFileSysDirEntry_t* p );
  179. // Return the last error code generated by the file system.
  180. cmFsRC_t cmFileSysErrorCode( cmFileSysH_t h );
  181. //-------------------------------------------------------------------------------------------------
  182. // Global file system functions:
  183. // These functions work using a global cmFileSysH created by cmFsInitialize().
  184. // The functions are otherwise just wrappers for the same named function above.
  185. cmFsRC_t cmFsInitialize( cmCtx_t* ctx, const cmChar_t* appNameStr );
  186. cmFsRC_t cmFsFinalize();
  187. const cmChar_t* cmFsAppName();
  188. const cmChar_t* cmFsPrefsDir();
  189. const cmChar_t* cmFsRsrcDir();
  190. const cmChar_t* cmFsUserDir();
  191. bool cmFsCanWriteToDir( const cmChar_t* dirStr );
  192. bool cmFsIsDir( const cmChar_t* dirStr );
  193. bool cmFsIsFile( const cmChar_t* fnStr );
  194. bool cmFsIsLink( const cmChar_t* fnStr );
  195. const cmChar_t* cmFsVMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  196. const cmChar_t* cmFsMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  197. const cmChar_t* cmFsVMakeUserFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  198. const cmChar_t* cmFsMakeUserFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  199. const cmChar_t* cmFsVMakeDir( const cmChar_t* dirPrefix, va_list vl );
  200. const cmChar_t* cmFsMakeDir( const cmChar_t* dirPrefix, ... );
  201. const cmChar_t* cmFsVMakeUserDir( const cmChar_t* dirPrefix, va_list vl );
  202. const cmChar_t* cmFsMakeUserDir( const cmChar_t* dirPrefix, ... );
  203. const cmChar_t* cmFsMakeDirFn( const cmChar_t* dir, const cmChar_t* fn );
  204. const cmChar_t* cmFsMakeUserDirFn(const cmChar_t* dir, const cmChar_t* fn );
  205. void cmFsFreeFn( const cmChar_t* fn );
  206. cmFsRC_t cmFsGenFn( const cmChar_t* dir, const cmChar_t* prefixStr, const cmChar_t* extStr, const cmChar_t** fnPtr );
  207. cmFsRC_t cmFsMkDir( const cmChar_t* dir );
  208. cmFsRC_t cmFsMkUserDir( const cmChar_t* dir );
  209. cmFsRC_t cmFsMkDirAll( const cmChar_t* dir );
  210. cmFsRC_t cmFsMkUserDirAll( const cmChar_t* dir );
  211. cmFileSysPathPart_t* cmFsPathParts( const cmChar_t* pathNameStr );
  212. void cmFsFreePathParts( cmFileSysPathPart_t* p );
  213. cmChar_t** cmFsDirParts( const cmChar_t* dirStr );
  214. void cmFsFreeDirParts( cmChar_t** dirStrArray );
  215. unsigned cmFsDirPartsCount( cmChar_t** dirStrArray );
  216. cmChar_t* cmFsFormDir( cmChar_t** dirStrArray, unsigned n );
  217. void cmFsFreeDir( const cmChar_t* dir );
  218. cmFileSysDirEntry_t* cmFsDirEntries( const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
  219. void cmFsDirFreeEntries( cmFileSysDirEntry_t* p );
  220. cmFsRC_t cmFsErrorCode();
  221. // Test and example function to demonstrate the use of the functions in cmFileSys.h
  222. cmFsRC_t cmFileSysTest( cmCtx_t* ctx );
  223. //)
  224. #ifdef __cplusplus
  225. }
  226. #endif
  227. #endif