libcm is a C development framework with an emphasis on audio signal processing applications.
Nevar pievienot vairāk kā 25 tēmas Tēmai ir jāsākas ar burtu vai ciparu, tā var saturēt domu zīmes ('-') un var būt līdz 35 simboliem gara.

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