1 /* 2 Copyright (C) 2015-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4pathd.ctr 12 */ 13 14 #ifndef DK4PATHD_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4PATHD_H_INCLUDED 1 17 18 19 /** @file 20 String operations for path names 21 (dkChar characters). 22 */ 23 24 #ifndef DK4CONF_H_INCLUDED 25 #if DK4_BUILDING_DKTOOLS4 26 #include "dk4conf.h" 27 #else 28 #include <dktools-4/dk4conf.h> 29 #endif 30 #endif 31 32 #ifndef DK4TYPES_H_INCLUDED 33 #if DK4_BUILDING_DKTOOLS4 34 #include <libdk4base/dk4types.h> 35 #else 36 #include <dktools-4/dk4types.h> 37 #endif 38 #endif 39 40 #ifndef DK4ERROR_H_INCLUDED 41 #if DK4_BUILDING_DKTOOLS4 42 #include <libdk4base/dk4error.h> 43 #else 44 #include <dktools-4/dk4error.h> 45 #endif 46 #endif 47 48 #if DK4_HAVE_WCHAR_H 49 #ifndef WCHAR_H_INCLUDED 50 #include <wchar.h> 51 #define WCHAR_H_INCLUDED 1 52 #endif 53 #endif 54 55 #ifdef __cplusplus 56 extern "C" { 57 #endif 58 59 /** Check whether a file name is an absolute path. 60 CRT on Windows: Not used. 61 @param path Path name to check. 62 @return 1 for absolute path, 0 for other path. 63 */ 64 int 65 dk4path_is_absolute(const dkChar *path); 66 67 /** Check whether a file name is a relative path. 68 CRT on Windows: Not used. 69 @param path Path name to check. 70 @return 1 for absolute path, 0 for other path. 71 */ 72 int 73 dk4path_is_relative(const dkChar *path); 74 75 /** Append path filename to path name already stored in buffer. 76 Resolve . and .. for current directory and parent directory. 77 CRT on Windows: Optional, disabling CRT degrades performance. 78 @param buffer Buffer already containing a path. 79 @param sz Buffer size. 80 @param filename Relative file name to append to buffer. 81 @param erp Error report, may be NULL. 82 @return 1 on success, 0 on error. 83 84 Error codes: 85 - DK4_E_INVALID_ARGUMENTS<br> 86 if buffer or filename is NULL or sz is 0, 87 - DK4_E_MATH_OVERFLOW<br> 88 if filename is too long, 89 - DK4_E_MEMORY<br> 90 if allocation of a filename copy fails, 91 - DK4_E_SYNTAX<br> 92 if too many .. in filename, 93 - DK4_E_BUFFER_TOO_SMALL<br> 94 if buffer size is too small. 95 */ 96 int 97 dk4path_append( 98 dkChar *buffer, size_t sz, const dkChar *filename, dk4_er_t *erp 99 ); 100 101 102 /** Find pointer to suffix. 103 CRT on Windows: Not used. 104 @param filename File name to find suffix for. 105 @param erp Error report, may be NULL. 106 @return Pointer to suffix dot if found, NULL otherwise. 107 108 Error codes: 109 - DK4_E_INVALID_ARGUMENTS<br> 110 if filename is NULL, 111 - DK4_E_NOT_FOUND<br> 112 if the file name does not contain a suffix. 113 */ 114 dkChar * 115 dk4path_get_suffix(const dkChar *filename, dk4_er_t *erp); 116 117 118 /** Correct file name separators from slash to backslash on Windows, 119 vice versa on other systems. 120 CRT on Windows: Not used. 121 @param filename File name to correct. 122 */ 123 void 124 dk4path_correct_sep(dkChar *filename); 125 126 /** Check whether file name needs expansion on Windows. 127 CRT on Windows: Not used. 128 @param filename File name to check. 129 @return 1 if expansion is necessary, 0 otherwise. 130 */ 131 int 132 dk4path_must_expand(const dkChar *filename); 133 134 /** Check whether filename is in the specified parent directory. 135 It may be equal to parent or below the parent directory. 136 @param filename File or directory name to check. 137 @param parent Parent directory. 138 @param erp Error report, may be NULL. 139 @return 1 for true, 0 for false. 140 141 Error codes: 142 - DK4_E_INVALID_ARGUMENTS<br> 143 if filename or parent is NULL, 144 - DK4_E_BUFFER_TOO_SMALL<br> 145 if filename is too long for an internal buffer. 146 */ 147 int 148 dk4path_is_in_subdir(const dkChar *filename,const dkChar *parent,dk4_er_t *erp); 149 150 /** Create file name with specified suffix. 151 @param pdst Destination buffer. 152 @param szdst Size of pdst (number of dkChar). 153 @param srcname Source file name. 154 @param newsu New file suffix. 155 @param erp Error report, may be NULL. 156 @return 1 on success, 0 on error. 157 158 Error codes: 159 - DK4_E_INVALID_ARGUMENTS<br> 160 if pdst or srcname or newsu is NULL or szdst is 0, 161 - DK4_E_BUFFER_TOO_SMALL<br> 162 if the dst buffer is too small. 163 - DK4_E_MATH_OVERFLOW<br> 164 if a mathematical overflow occured in size calculation, 165 */ 166 int 167 dk4path_set_suffix( 168 dkChar *pdst, 169 size_t szdst, 170 dkChar const *srcname, 171 dkChar const *newsu, 172 dk4_er_t *erp 173 ); 174 175 /** Create a dynamic copy of a file name with changed suffix. 176 @param srcname Old file name. 177 @param newsu New suffix. 178 @param erp Error report, may be NULL. 179 @return Valid pointer to changed file name on success, NULL on error. 180 On success call dk4mem_free() on the pointer when no longer needed 181 to release the memory. 182 183 Error codes: 184 - DK4_E_INVALID_ARGUMENTS<br> 185 if srcname or newsu is NULL, 186 - DK4_E_BUG<br> 187 if a bug occured, 188 - DK4_E_MATH_OVERFLOW<br> 189 if a mathematical overflow occured in size calculation, 190 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 191 with mem.elsize and mem.nelem set if there is not enough memory 192 available. 193 */ 194 dkChar * 195 dk4path_dup_change_suffix( 196 dkChar const *srcname, 197 dkChar const *newsu, 198 dk4_er_t *erp 199 ); 200 201 /** Calculate buffer size required to concatenate a directory 202 name and a file name. 203 @param dirname Directory name. 204 @param filename File name. 205 @param erp Error report, may be NULL. 206 @return Buffer size for concatenated names including the finalizer 207 byte on success, 0 on error. 208 209 Error codes: 210 - DK4_E_INVALID_ARGUMENTS<br> 211 if dirname or filename is NULL, 212 - DK4_E_MATH_OVERFLOW<br> 213 if the calculation results in a numeric overflow. 214 */ 215 size_t 216 dk4path_concatenate_size( 217 dkChar const *dirname, 218 dkChar const *filename, 219 dk4_er_t *erp 220 ); 221 222 /** Concatenate a directory name and a file name into an existing buffer. 223 This function simply concatenates directory name and file name, 224 . and .. for current and parent directory are not resolved. 225 @param buffer Result buffer for combined file name. 226 @param szbuf Buffer size (number of dkChar). 227 @param dirn Directory name. 228 @param filen File name. 229 @param erp Error report, may be NULL. 230 @return 1 on success, 0 on error. 231 232 Error codes: 233 - DK4_E_INVALID_ARGUMENTS<br> 234 if buffer, dirn or filen is NULL or szbuf is 0, 235 - DK4_E_BUFFER_TOO_SMALL<br> 236 if the buffer is too small. 237 */ 238 int 239 dk4path_concatenate_buffer( 240 dkChar *buffer, 241 size_t szbuf, 242 dkChar const *dirn, 243 dkChar const *filen, 244 dk4_er_t *erp 245 ); 246 247 /** Concatenate a directory name and a file name into newly 248 allocated memory. 249 This function simply concatenates directory name and file name, 250 . and .. for current and parent directory are not resolved. 251 @param dirn Directory name. 252 @param filen File name. 253 @param erp Error report, may be NULL. 254 @return Valid pointer to newly allocated memory containing the 255 concatenation on success, NULL on error. 256 On success use dk4mem_free() to release the memory when done 257 with it. 258 259 Error codes: 260 - DK4_E_INVALID_ARGUMENTS<br> 261 if dirn or filen is NULL, 262 - DK4_E_MATH_OVERFLOW<br> 263 if the size calculation results in a numeric overflow. 264 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 265 if the memory allocation failed, 266 - DK4_E_BUFFER_TOO_SMALL<br> 267 if the buffer is too small. 268 */ 269 dkChar * 270 dk4path_concatenate_new( 271 dkChar const *dirn, 272 dkChar const *filen, 273 dk4_er_t *erp 274 ); 275 276 #ifdef __cplusplus 277 } 278 #endif 279 280 281 282 #endif 283