00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Licensed to the Apache Software Foundation (ASF) under one 00005 * or more contributor license agreements. See the NOTICE file 00006 * distributed with this work for additional information 00007 * regarding copyright ownership. The ASF licenses this file 00008 * to you under the Apache License, Version 2.0 (the 00009 * "License"); you may not use this file except in compliance 00010 * with the License. You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, 00015 * software distributed under the License is distributed on an 00016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00017 * KIND, either express or implied. See the License for the 00018 * specific language governing permissions and limitations 00019 * under the License. 00020 * ==================================================================== 00021 * @endcopyright 00022 * 00023 * @file svn_io.h 00024 * @brief General file I/O for Subversion 00025 */ 00026 00027 /* ==================================================================== */ 00028 00029 00030 #ifndef SVN_IO_H 00031 #define SVN_IO_H 00032 00033 #include <apr.h> 00034 #include <apr_pools.h> 00035 #include <apr_time.h> 00036 #include <apr_hash.h> 00037 #include <apr_tables.h> 00038 #include <apr_file_io.h> 00039 #include <apr_file_info.h> 00040 #include <apr_thread_proc.h> /* for apr_proc_t, apr_exit_why_e */ 00041 00042 #include "svn_types.h" 00043 #include "svn_string.h" 00044 #include "svn_checksum.h" 00045 00046 #ifdef __cplusplus 00047 extern "C" { 00048 #endif /* __cplusplus */ 00049 00050 00051 00052 /** Used as an argument when creating temporary files to indicate 00053 * when a file should be removed. 00054 * 00055 * @since New in 1.4. 00056 * 00057 * Not specifying any of these means no removal at all. */ 00058 typedef enum svn_io_file_del_t 00059 { 00060 /** No deletion ever */ 00061 svn_io_file_del_none = 0, 00062 /** Remove when the file is closed */ 00063 svn_io_file_del_on_close, 00064 /** Remove when the associated pool is cleared */ 00065 svn_io_file_del_on_pool_cleanup 00066 } svn_io_file_del_t; 00067 00068 /** A set of directory entry data elements as returned by svn_io_get_dirents 00069 * 00070 * Note that the first two fields are exactly identical to svn_io_dirent_t 00071 * to allow returning a svn_io_dirent2_t as a svn_io_dirent_t. 00072 * 00073 * Use svn_io_dirent2_create() to create new svn_dirent2_t instances or 00074 * svn_io_dirent2_dup() to duplicate an existing instance. 00075 * 00076 * @since New in 1.7. 00077 */ 00078 typedef struct svn_io_dirent2_t { 00079 /* New fields must be added at the end to preserve binary compatibility */ 00080 00081 /** The kind of this entry. */ 00082 svn_node_kind_t kind; 00083 00084 /** If @c kind is #svn_node_file, whether this entry is a special file; 00085 * else FALSE. 00086 * 00087 * @see svn_io_check_special_path(). 00088 */ 00089 svn_boolean_t special; 00090 00091 /** The filesize of this entry or undefined for a directory */ 00092 svn_filesize_t filesize; 00093 00094 /** The time the file was last modified */ 00095 apr_time_t mtime; 00096 00097 /* Don't forget to update svn_io_dirent2_dup() when adding new fields */ 00098 } svn_io_dirent2_t; 00099 00100 00101 /** Creates a new #svn_io_dirent2_t structure 00102 * 00103 * @since New in 1.7. 00104 */ 00105 svn_io_dirent2_t * 00106 svn_io_dirent2_create(apr_pool_t *result_pool); 00107 00108 /** Duplicates a @c svn_io_dirent2_t structure into @a result_pool. 00109 * 00110 * @since New in 1.7. 00111 */ 00112 svn_io_dirent2_t * 00113 svn_io_dirent2_dup(const svn_io_dirent2_t *item, 00114 apr_pool_t *result_pool); 00115 00116 /** Represents the kind and special status of a directory entry. 00117 * 00118 * Note that the first two fields are exactly identical to svn_io_dirent2_t 00119 * to allow returning a svn_io_dirent2_t as a svn_io_dirent_t. 00120 * 00121 * @since New in 1.3. 00122 */ 00123 typedef struct svn_io_dirent_t { 00124 /** The kind of this entry. */ 00125 svn_node_kind_t kind; 00126 /** If @c kind is #svn_node_file, whether this entry is a special file; 00127 * else FALSE. 00128 * 00129 * @see svn_io_check_special_path(). 00130 */ 00131 svn_boolean_t special; 00132 } svn_io_dirent_t; 00133 00134 /** Determine the @a kind of @a path. @a path should be UTF-8 encoded. 00135 * 00136 * If @a path is a file, set @a *kind to #svn_node_file. 00137 * 00138 * If @a path is a directory, set @a *kind to #svn_node_dir. 00139 * 00140 * If @a path does not exist, set @a *kind to #svn_node_none. 00141 * 00142 * If @a path exists but is none of the above, set @a *kind to 00143 * #svn_node_unknown. 00144 * 00145 * If @a path is not a valid pathname, set @a *kind to #svn_node_none. If 00146 * unable to determine @a path's kind for any other reason, return an error, 00147 * with @a *kind's value undefined. 00148 * 00149 * Use @a pool for temporary allocations. 00150 * 00151 * @see svn_node_kind_t 00152 */ 00153 svn_error_t * 00154 svn_io_check_path(const char *path, 00155 svn_node_kind_t *kind, 00156 apr_pool_t *pool); 00157 00158 /** 00159 * Like svn_io_check_path(), but also set *is_special to @c TRUE if 00160 * the path is not a normal file. 00161 * 00162 * @since New in 1.1. 00163 */ 00164 svn_error_t * 00165 svn_io_check_special_path(const char *path, 00166 svn_node_kind_t *kind, 00167 svn_boolean_t *is_special, 00168 apr_pool_t *pool); 00169 00170 /** Like svn_io_check_path(), but resolve symlinks. This returns the 00171 same varieties of @a kind as svn_io_check_path(). */ 00172 svn_error_t * 00173 svn_io_check_resolved_path(const char *path, 00174 svn_node_kind_t *kind, 00175 apr_pool_t *pool); 00176 00177 00178 /** Open a new file (for reading and writing) with a unique name based on 00179 * utf-8 encoded @a filename, in the directory @a dirpath. The file handle is 00180 * returned in @a *file, and the name, which ends with @a suffix, is returned 00181 * in @a *unique_name, also utf8-encoded. Either @a file or @a unique_name 00182 * may be @c NULL. If @a file is @c NULL, the file will be created but not 00183 * open. 00184 * 00185 * If @a delete_when is #svn_io_file_del_on_close, then the @c APR_DELONCLOSE 00186 * flag will be used when opening the file. The @c APR_BUFFERED flag will 00187 * always be used. 00188 * 00189 * The first attempt will just append @a suffix. If the result is not 00190 * a unique name, then subsequent attempts will append a dot, 00191 * followed by an iteration number ("2", then "3", and so on), 00192 * followed by the suffix. For example, successive calls to 00193 * 00194 * svn_io_open_uniquely_named(&f, &u, "tests/t1/A/D/G", "pi", ".tmp", ...) 00195 * 00196 * will open 00197 * 00198 * tests/t1/A/D/G/pi.tmp 00199 * tests/t1/A/D/G/pi.2.tmp 00200 * tests/t1/A/D/G/pi.3.tmp 00201 * tests/t1/A/D/G/pi.4.tmp 00202 * tests/t1/A/D/G/pi.5.tmp 00203 * ... 00204 * 00205 * Assuming @a suffix is non-empty, @a *unique_name will never be exactly 00206 * the same as @a filename, even if @a filename does not exist. 00207 * 00208 * If @a dirpath is NULL, then the directory returned by svn_io_temp_dir() 00209 * will be used. 00210 * 00211 * If @a filename is NULL, then "tempfile" will be used. 00212 * 00213 * If @a suffix is NULL, then ".tmp" will be used. 00214 * 00215 * Allocates @a *file and @a *unique_name in @a result_pool. All 00216 * intermediate allocations will be performed in @a scratch_pool. 00217 * 00218 * If no unique name can be found, #SVN_ERR_IO_UNIQUE_NAMES_EXHAUSTED is 00219 * the error returned. 00220 * 00221 * Claim of Historical Inevitability: this function was written 00222 * because 00223 * 00224 * - tmpnam() is not thread-safe. 00225 * - tempname() tries standard system tmp areas first. 00226 * 00227 * @since New in 1.6 00228 */ 00229 svn_error_t * 00230 svn_io_open_uniquely_named(apr_file_t **file, 00231 const char **unique_name, 00232 const char *dirpath, 00233 const char *filename, 00234 const char *suffix, 00235 svn_io_file_del_t delete_when, 00236 apr_pool_t *result_pool, 00237 apr_pool_t *scratch_pool); 00238 00239 00240 /** Create a writable file, with an arbitrary and unique name, in the 00241 * directory @a dirpath. Set @a *temp_path to its full path, and set 00242 * @a *file to the file handle, both allocated from @a result_pool. Either 00243 * @a file or @a unique_name may be @c NULL. If @a file is @c NULL, the file 00244 * will be created but not open. 00245 * 00246 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir(). 00247 * (Note that when using the system-provided temp directory, it may not 00248 * be possible to atomically rename the resulting file due to cross-device 00249 * issues.) 00250 * 00251 * The file will be deleted according to @a delete_when. If @a delete_when 00252 * is @c svn_io_file_del_on_close and @a file is @c NULL, the file will be 00253 * deleted before this function returns. 00254 * 00255 * When passing @c svn_io_file_del_none please don't forget to eventually 00256 * remove the temporary file to avoid filling up the system temp directory. 00257 * It is often appropriate to bind the lifetime of the temporary file to 00258 * the lifetime of a pool by using @c svn_io_file_del_on_pool_cleanup. 00259 * 00260 * Temporary allocations will be performed in @a scratch_pool. 00261 * 00262 * @since New in 1.6 00263 * @see svn_stream_open_unique() 00264 */ 00265 svn_error_t * 00266 svn_io_open_unique_file3(apr_file_t **file, 00267 const char **temp_path, 00268 const char *dirpath, 00269 svn_io_file_del_t delete_when, 00270 apr_pool_t *result_pool, 00271 apr_pool_t *scratch_pool); 00272 00273 00274 /** Like svn_io_open_uniquely_named(), but takes a joined dirpath and 00275 * filename, and a single pool. 00276 * 00277 * @since New in 1.4 00278 * 00279 * @deprecated Provided for backward compatibility with the 1.5 API 00280 */ 00281 SVN_DEPRECATED 00282 svn_error_t * 00283 svn_io_open_unique_file2(apr_file_t **f, 00284 const char **unique_name_p, 00285 const char *path, 00286 const char *suffix, 00287 svn_io_file_del_t delete_when, 00288 apr_pool_t *pool); 00289 00290 /** Like svn_io_open_unique_file2, but can't delete on pool cleanup. 00291 * 00292 * @deprecated Provided for backward compatibility with the 1.3 API 00293 * 00294 * @note In 1.4 the API was extended to require either @a f or 00295 * @a unique_name_p (the other can be NULL). Before that, both were 00296 * required. 00297 */ 00298 SVN_DEPRECATED 00299 svn_error_t * 00300 svn_io_open_unique_file(apr_file_t **f, 00301 const char **unique_name_p, 00302 const char *path, 00303 const char *suffix, 00304 svn_boolean_t delete_on_close, 00305 apr_pool_t *pool); 00306 00307 00308 /** 00309 * Like svn_io_open_unique_file(), except that instead of creating a 00310 * file, a symlink is generated that references the path @a dest. 00311 * 00312 * @since New in 1.1. 00313 */ 00314 svn_error_t * 00315 svn_io_create_unique_link(const char **unique_name_p, 00316 const char *path, 00317 const char *dest, 00318 const char *suffix, 00319 apr_pool_t *pool); 00320 00321 00322 /** 00323 * Set @a *dest to the path that the symlink at @a path references. 00324 * Allocate the string from @a pool. 00325 * 00326 * @since New in 1.1. 00327 */ 00328 svn_error_t * 00329 svn_io_read_link(svn_string_t **dest, 00330 const char *path, 00331 apr_pool_t *pool); 00332 00333 00334 /** Set @a *dir to a directory path (allocated in @a pool) deemed 00335 * usable for the creation of temporary files and subdirectories. 00336 */ 00337 svn_error_t * 00338 svn_io_temp_dir(const char **dir, 00339 apr_pool_t *pool); 00340 00341 00342 /** Copy @a src to @a dst atomically, in a "byte-for-byte" manner. 00343 * Overwrite @a dst if it exists, else create it. Both @a src and @a dst 00344 * are utf8-encoded filenames. If @a copy_perms is TRUE, set @a dst's 00345 * permissions to match those of @a src. 00346 */ 00347 svn_error_t * 00348 svn_io_copy_file(const char *src, 00349 const char *dst, 00350 svn_boolean_t copy_perms, 00351 apr_pool_t *pool); 00352 00353 00354 /** Copy permission flags from @a src onto the file at @a dst. Both 00355 * filenames are utf8-encoded filenames. 00356 * 00357 * @since New in 1.6. 00358 */ 00359 svn_error_t * 00360 svn_io_copy_perms(const char *src, 00361 const char *dst, 00362 apr_pool_t *pool); 00363 00364 00365 /** 00366 * Copy symbolic link @a src to @a dst atomically. Overwrite @a dst 00367 * if it exists, else create it. Both @a src and @a dst are 00368 * utf8-encoded filenames. After copying, the @a dst link will point 00369 * to the same thing @a src does. 00370 * 00371 * @since New in 1.1. 00372 */ 00373 svn_error_t * 00374 svn_io_copy_link(const char *src, 00375 const char *dst, 00376 apr_pool_t *pool); 00377 00378 00379 /** Recursively copy directory @a src into @a dst_parent, as a new entry named 00380 * @a dst_basename. If @a dst_basename already exists in @a dst_parent, 00381 * return error. @a copy_perms will be passed through to svn_io_copy_file() 00382 * when any files are copied. @a src, @a dst_parent, and @a dst_basename are 00383 * all utf8-encoded. 00384 * 00385 * If @a cancel_func is non-NULL, invoke it with @a cancel_baton at 00386 * various points during the operation. If it returns any error 00387 * (typically #SVN_ERR_CANCELLED), return that error immediately. 00388 */ 00389 svn_error_t * 00390 svn_io_copy_dir_recursively(const char *src, 00391 const char *dst_parent, 00392 const char *dst_basename, 00393 svn_boolean_t copy_perms, 00394 svn_cancel_func_t cancel_func, 00395 void *cancel_baton, 00396 apr_pool_t *pool); 00397 00398 00399 /** Create directory @a path on the file system, creating intermediate 00400 * directories as required, like <tt>mkdir -p</tt>. Report no error if @a 00401 * path already exists. @a path is utf8-encoded. 00402 * 00403 * This is essentially a wrapper for apr_dir_make_recursive(), passing 00404 * @c APR_OS_DEFAULT as the permissions. 00405 */ 00406 svn_error_t * 00407 svn_io_make_dir_recursively(const char *path, 00408 apr_pool_t *pool); 00409 00410 00411 /** Set @a *is_empty_p to @c TRUE if directory @a path is empty, else to 00412 * @c FALSE if it is not empty. @a path must be a directory, and is 00413 * utf8-encoded. Use @a pool for temporary allocation. 00414 */ 00415 svn_error_t * 00416 svn_io_dir_empty(svn_boolean_t *is_empty_p, 00417 const char *path, 00418 apr_pool_t *pool); 00419 00420 00421 /** Append @a src to @a dst. @a dst will be appended to if it exists, else it 00422 * will be created. Both @a src and @a dst are utf8-encoded. 00423 */ 00424 svn_error_t * 00425 svn_io_append_file(const char *src, 00426 const char *dst, 00427 apr_pool_t *pool); 00428 00429 00430 /** Make a file as read-only as the operating system allows. 00431 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is 00432 * @c TRUE, don't fail if the target file doesn't exist. 00433 * 00434 * If @a path is a symlink, do nothing. 00435 * 00436 * @note If @a path is a directory, act on it as though it were a 00437 * file, as described above, but note that you probably don't want to 00438 * call this function on directories. We have left it effective on 00439 * directories for compatibility reasons, but as its name implies, it 00440 * should be used only for files. 00441 */ 00442 svn_error_t * 00443 svn_io_set_file_read_only(const char *path, 00444 svn_boolean_t ignore_enoent, 00445 apr_pool_t *pool); 00446 00447 00448 /** Make a file as writable as the operating system allows. 00449 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is 00450 * @c TRUE, don't fail if the target file doesn't exist. 00451 * @warning On Unix this function will do the equivalent of chmod a+w path. 00452 * If this is not what you want you should not use this function, but rather 00453 * use apr_file_perms_set(). 00454 * 00455 * If @a path is a symlink, do nothing. 00456 * 00457 * @note If @a path is a directory, act on it as though it were a 00458 * file, as described above, but note that you probably don't want to 00459 * call this function on directories. We have left it effective on 00460 * directories for compatibility reasons, but as its name implies, it 00461 * should be used only for files. 00462 */ 00463 svn_error_t * 00464 svn_io_set_file_read_write(const char *path, 00465 svn_boolean_t ignore_enoent, 00466 apr_pool_t *pool); 00467 00468 00469 /** Similar to svn_io_set_file_read_* functions. 00470 * Change the read-write permissions of a file. 00471 * @since New in 1.1. 00472 * 00473 * When making @a path read-write on operating systems with unix style 00474 * permissions, set the permissions on @a path to the permissions that 00475 * are set when a new file is created (effectively honoring the user's 00476 * umask). 00477 * 00478 * When making the file read-only on operating systems with unix style 00479 * permissions, remove all write permissions. 00480 * 00481 * On other operating systems, toggle the file's "writability" as much as 00482 * the operating system allows. 00483 * 00484 * @a path is the utf8-encoded path to the file. If @a enable_write 00485 * is @c TRUE, then make the file read-write. If @c FALSE, make it 00486 * read-only. If @a ignore_enoent is @c TRUE, don't fail if the target 00487 * file doesn't exist. 00488 * 00489 * @deprecated Provided for backward compatibility with the 1.3 API. 00490 */ 00491 SVN_DEPRECATED 00492 svn_error_t * 00493 svn_io_set_file_read_write_carefully(const char *path, 00494 svn_boolean_t enable_write, 00495 svn_boolean_t ignore_enoent, 00496 apr_pool_t *pool); 00497 00498 /** Set @a path's "executability" (but do nothing if it is a symlink). 00499 * 00500 * @a path is the utf8-encoded path to the file. If @a executable 00501 * is @c TRUE, then make the file executable. If @c FALSE, make it 00502 * non-executable. If @a ignore_enoent is @c TRUE, don't fail if the target 00503 * file doesn't exist. 00504 * 00505 * When making the file executable on operating systems with unix style 00506 * permissions, never add an execute permission where there is not 00507 * already a read permission: that is, only make the file executable 00508 * for the user, group or world if the corresponding read permission 00509 * is already set for user, group or world. 00510 * 00511 * When making the file non-executable on operating systems with unix style 00512 * permissions, remove all execute permissions. 00513 * 00514 * On other operating systems, toggle the file's "executability" as much as 00515 * the operating system allows. 00516 * 00517 * @note If @a path is a directory, act on it as though it were a 00518 * file, as described above, but note that you probably don't want to 00519 * call this function on directories. We have left it effective on 00520 * directories for compatibility reasons, but as its name implies, it 00521 * should be used only for files. 00522 */ 00523 svn_error_t * 00524 svn_io_set_file_executable(const char *path, 00525 svn_boolean_t executable, 00526 svn_boolean_t ignore_enoent, 00527 apr_pool_t *pool); 00528 00529 /** Determine whether a file is executable by the current user. 00530 * Set @a *executable to @c TRUE if the file @a path is executable by the 00531 * current user, otherwise set it to @c FALSE. 00532 * 00533 * On Windows and on platforms without userids, always returns @c FALSE. 00534 */ 00535 svn_error_t * 00536 svn_io_is_file_executable(svn_boolean_t *executable, 00537 const char *path, 00538 apr_pool_t *pool); 00539 00540 00541 /** Read a line from @a file into @a buf, but not exceeding @a *limit bytes. 00542 * Does not include newline, instead '\\0' is put there. 00543 * Length (as in strlen) is returned in @a *limit. 00544 * @a buf should be pre-allocated. 00545 * @a file should be already opened. 00546 * 00547 * When the file is out of lines, @c APR_EOF will be returned. 00548 */ 00549 svn_error_t * 00550 svn_io_read_length_line(apr_file_t *file, 00551 char *buf, 00552 apr_size_t *limit, 00553 apr_pool_t *pool); 00554 00555 00556 /** Set @a *apr_time to the time of last modification of the contents of the 00557 * file @a path. @a path is utf8-encoded. 00558 * 00559 * @note This is the APR mtime which corresponds to the traditional mtime 00560 * on Unix, and the last write time on Windows. 00561 */ 00562 svn_error_t * 00563 svn_io_file_affected_time(apr_time_t *apr_time, 00564 const char *path, 00565 apr_pool_t *pool); 00566 00567 /** Set the timestamp of file @a path to @a apr_time. @a path is 00568 * utf8-encoded. 00569 * 00570 * @note This is the APR mtime which corresponds to the traditional mtime 00571 * on Unix, and the last write time on Windows. 00572 */ 00573 svn_error_t * 00574 svn_io_set_file_affected_time(apr_time_t apr_time, 00575 const char *path, 00576 apr_pool_t *pool); 00577 00578 /** Sleep to ensure that any files modified after we exit have a different 00579 * timestamp than the one we recorded. If @a path is not NULL, check if we 00580 * can determine how long we should wait for a new timestamp on the filesystem 00581 * containing @a path, an existing file or directory. If @a path is NULL or we 00582 * can't determine the timestamp resolution, sleep until the next second. 00583 * 00584 * Use @a pool for any necessary allocations. @a pool can be null if @a path 00585 * is NULL. 00586 * 00587 * Errors while retrieving the timestamp resolution will result in sleeping 00588 * to the next second, to keep the working copy stable in error conditions. 00589 * 00590 * @since New in 1.6. 00591 */ 00592 void 00593 svn_io_sleep_for_timestamps(const char *path, apr_pool_t *pool); 00594 00595 /** Set @a *different_p to non-zero if @a file1 and @a file2 have different 00596 * sizes, else set to zero. Both @a file1 and @a file2 are utf8-encoded. 00597 * 00598 * Setting @a *different_p to zero does not mean the files definitely 00599 * have the same size, it merely means that the sizes are not 00600 * definitely different. That is, if the size of one or both files 00601 * cannot be determined, then the sizes are not known to be different, 00602 * so @a *different_p is set to 0. 00603 */ 00604 svn_error_t * 00605 svn_io_filesizes_different_p(svn_boolean_t *different_p, 00606 const char *file1, 00607 const char *file2, 00608 apr_pool_t *pool); 00609 00610 00611 /** Return in @a *checksum the checksum of type @a kind of @a file 00612 * Use @a pool for temporary allocations and to allocate @a *checksum. 00613 * 00614 * @since New in 1.6. 00615 */ 00616 svn_error_t * 00617 svn_io_file_checksum2(svn_checksum_t **checksum, 00618 const char *file, 00619 svn_checksum_kind_t kind, 00620 apr_pool_t *pool); 00621 00622 00623 /** Put the md5 checksum of @a file into @a digest. 00624 * @a digest points to @c APR_MD5_DIGESTSIZE bytes of storage. 00625 * Use @a pool only for temporary allocations. 00626 * 00627 * @deprecated Provided for backward compatibility with the 1.5 API. 00628 */ 00629 SVN_DEPRECATED 00630 svn_error_t * 00631 svn_io_file_checksum(unsigned char digest[], 00632 const char *file, 00633 apr_pool_t *pool); 00634 00635 00636 /** Set @a *same to TRUE if @a file1 and @a file2 have the same 00637 * contents, else set it to FALSE. Use @a pool for temporary allocations. 00638 */ 00639 svn_error_t * 00640 svn_io_files_contents_same_p(svn_boolean_t *same, 00641 const char *file1, 00642 const char *file2, 00643 apr_pool_t *pool); 00644 00645 /** Create file at utf8-encoded @a file with contents @a contents. 00646 * @a file must not already exist. 00647 * Use @a pool for memory allocations. 00648 */ 00649 svn_error_t * 00650 svn_io_file_create(const char *file, 00651 const char *contents, 00652 apr_pool_t *pool); 00653 00654 /** 00655 * Lock file at @a lock_file. If @a exclusive is TRUE, 00656 * obtain exclusive lock, otherwise obtain shared lock. 00657 * Lock will be automatically released when @a pool is cleared or destroyed. 00658 * Use @a pool for memory allocations. 00659 * 00660 * @deprecated Provided for backward compatibility with the 1.0 API. 00661 */ 00662 SVN_DEPRECATED 00663 svn_error_t * 00664 svn_io_file_lock(const char *lock_file, 00665 svn_boolean_t exclusive, 00666 apr_pool_t *pool); 00667 00668 /** 00669 * Lock file at @a lock_file. If @a exclusive is TRUE, 00670 * obtain exclusive lock, otherwise obtain shared lock. 00671 * 00672 * If @a nonblocking is TRUE, do not wait for the lock if it 00673 * is not available: throw an error instead. 00674 * 00675 * Lock will be automatically released when @a pool is cleared or destroyed. 00676 * Use @a pool for memory allocations. 00677 * 00678 * @since New in 1.1. 00679 */ 00680 svn_error_t * 00681 svn_io_file_lock2(const char *lock_file, 00682 svn_boolean_t exclusive, 00683 svn_boolean_t nonblocking, 00684 apr_pool_t *pool); 00685 /** 00686 * Flush any unwritten data from @a file to disk. Use @a pool for 00687 * memory allocations. 00688 * 00689 * @since New in 1.1. 00690 */ 00691 svn_error_t * 00692 svn_io_file_flush_to_disk(apr_file_t *file, 00693 apr_pool_t *pool); 00694 00695 /** Copy the file whose basename (or relative path) is @a file within 00696 * directory @a src_path to the same basename (or relative path) within 00697 * directory @a dest_path. Overwrite the destination file if it already 00698 * exists. The destination directory (including any directory 00699 * components in @a name) must already exist. Set the destination 00700 * file's permissions to match those of the source. Use @a pool for 00701 * memory allocations. 00702 */ 00703 svn_error_t * 00704 svn_io_dir_file_copy(const char *src_path, 00705 const char *dest_path, 00706 const char *file, 00707 apr_pool_t *pool); 00708 00709 00710 /** Generic byte-streams 00711 * 00712 * @defgroup svn_io_byte_streams Generic byte streams 00713 * @{ 00714 */ 00715 00716 /** An abstract stream of bytes--either incoming or outgoing or both. 00717 * 00718 * The creator of a stream sets functions to handle read and write. 00719 * Both of these handlers accept a baton whose value is determined at 00720 * stream creation time; this baton can point to a structure 00721 * containing data associated with the stream. If a caller attempts 00722 * to invoke a handler which has not been set, it will generate a 00723 * runtime assertion failure. The creator can also set a handler for 00724 * close requests so that it can flush buffered data or whatever; 00725 * if a close handler is not specified, a close request on the stream 00726 * will simply be ignored. Note that svn_stream_close() does not 00727 * deallocate the memory used to allocate the stream structure; free 00728 * the pool you created the stream in to free that memory. 00729 * 00730 * The read and write handlers accept length arguments via pointer. 00731 * On entry to the handler, the pointed-to value should be the amount 00732 * of data which can be read or the amount of data to write. When the 00733 * handler returns, the value is reset to the amount of data actually 00734 * read or written. Handlers are obliged to complete a read or write 00735 * to the maximum extent possible; thus, a short read with no 00736 * associated error implies the end of the input stream, and a short 00737 * write should never occur without an associated error. 00738 * 00739 * In Subversion 1.7 reset support was added as an optional feature of 00740 * streams. If a stream implements resetting it allows reading the data 00741 * again after a successful call to svn_stream_reset(). 00742 */ 00743 typedef struct svn_stream_t svn_stream_t; 00744 00745 00746 00747 /** Read handler function for a generic stream. @see svn_stream_t. */ 00748 typedef svn_error_t *(*svn_read_fn_t)(void *baton, 00749 char *buffer, 00750 apr_size_t *len); 00751 00752 /** Skip data handler function for a generic stream. @see svn_stream_t 00753 * and svn_stream_skip(). 00754 * @since New in 1.7. 00755 */ 00756 typedef svn_error_t *(*svn_stream_skip_fn_t)(void *baton, 00757 apr_size_t len); 00758 00759 /** Write handler function for a generic stream. @see svn_stream_t. */ 00760 typedef svn_error_t *(*svn_write_fn_t)(void *baton, 00761 const char *data, 00762 apr_size_t *len); 00763 00764 /** Close handler function for a generic stream. @see svn_stream_t. */ 00765 typedef svn_error_t *(*svn_close_fn_t)(void *baton); 00766 00767 /** An opaque type which represents a mark on a stream. There is no 00768 * concrete definition of this type, it is a named type for stream 00769 * implementation specific baton pointers. 00770 * 00771 * @see svn_stream_mark(). 00772 * @since New in 1.7. 00773 */ 00774 typedef struct svn_stream_mark_t svn_stream_mark_t; 00775 00776 /** Mark handler function for a generic stream. @see svn_stream_t and 00777 * svn_stream_mark(). 00778 * 00779 * @since New in 1.7. 00780 */ 00781 typedef svn_error_t *(*svn_stream_mark_fn_t)(void *baton, 00782 svn_stream_mark_t **mark, 00783 apr_pool_t *pool); 00784 00785 /** Seek handler function for a generic stream. @see svn_stream_t and 00786 * svn_stream_seek(). 00787 * 00788 * @since New in 1.7. 00789 */ 00790 typedef svn_error_t *(*svn_stream_seek_fn_t)(void *baton, 00791 const svn_stream_mark_t *mark); 00792 00793 /** Create a generic stream. @see svn_stream_t. */ 00794 svn_stream_t * 00795 svn_stream_create(void *baton, 00796 apr_pool_t *pool); 00797 00798 /** Set @a stream's baton to @a baton */ 00799 void 00800 svn_stream_set_baton(svn_stream_t *stream, 00801 void *baton); 00802 00803 /** Set @a stream's read function to @a read_fn */ 00804 void 00805 svn_stream_set_read(svn_stream_t *stream, 00806 svn_read_fn_t read_fn); 00807 00808 /** Set @a stream's skip function to @a skip_fn 00809 * 00810 * @since New in 1.7 00811 */ 00812 void 00813 svn_stream_set_skip(svn_stream_t *stream, 00814 svn_stream_skip_fn_t skip_fn); 00815 00816 /** Set @a stream's write function to @a write_fn */ 00817 void 00818 svn_stream_set_write(svn_stream_t *stream, 00819 svn_write_fn_t write_fn); 00820 00821 /** Set @a stream's close function to @a close_fn */ 00822 void 00823 svn_stream_set_close(svn_stream_t *stream, 00824 svn_close_fn_t close_fn); 00825 00826 /** Set @a stream's mark function to @a mark_fn 00827 * 00828 * @since New in 1.7. 00829 */ 00830 void 00831 svn_stream_set_mark(svn_stream_t *stream, 00832 svn_stream_mark_fn_t mark_fn); 00833 00834 /** Set @a stream's seek function to @a seek_fn 00835 * 00836 * @since New in 1.7. 00837 */ 00838 void 00839 svn_stream_set_seek(svn_stream_t *stream, 00840 svn_stream_seek_fn_t seek_fn); 00841 00842 /** Create a stream that is empty for reading and infinite for writing. */ 00843 svn_stream_t * 00844 svn_stream_empty(apr_pool_t *pool); 00845 00846 /** Return a stream allocated in @a pool which forwards all requests 00847 * to @a stream. Destruction is explicitly excluded from forwarding. 00848 * 00849 * @see notes/destruction-of-stacked-resources 00850 * 00851 * @since New in 1.4. 00852 */ 00853 svn_stream_t * 00854 svn_stream_disown(svn_stream_t *stream, 00855 apr_pool_t *pool); 00856 00857 00858 /** Create a stream to read the file at @a path. It will be opened using 00859 * the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the perms. 00860 * If you'd like to use different values, then open the file yourself, and 00861 * use the svn_stream_from_aprfile2() interface. 00862 * 00863 * The stream will be returned in @a stream, and allocated from @a result_pool. 00864 * Temporary allocations will be performed in @a scratch_pool. 00865 * 00866 * @since New in 1.6 00867 */ 00868 svn_error_t * 00869 svn_stream_open_readonly(svn_stream_t **stream, 00870 const char *path, 00871 apr_pool_t *result_pool, 00872 apr_pool_t *scratch_pool); 00873 00874 00875 /** Create a stream to write a file at @a path. The file will be *created* 00876 * using the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the 00877 * perms. The file will be created "exclusively", so if it already exists, 00878 * then an error will be thrown. If you'd like to use different values, or 00879 * open an existing file, then open the file yourself, and use the 00880 * svn_stream_from_aprfile2() interface. 00881 * 00882 * The stream will be returned in @a stream, and allocated from @a result_pool. 00883 * Temporary allocations will be performed in @a scratch_pool. 00884 * 00885 * @since New in 1.6 00886 */ 00887 svn_error_t * 00888 svn_stream_open_writable(svn_stream_t **stream, 00889 const char *path, 00890 apr_pool_t *result_pool, 00891 apr_pool_t *scratch_pool); 00892 00893 00894 /** Create a writable stream to a file in the directory @a dirpath. 00895 * The file will have an arbitrary and unique name, and the full path 00896 * will be returned in @a temp_path. The stream will be returned in 00897 * @a stream. Both will be allocated from @a result_pool. 00898 * 00899 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir(). 00900 * (Note that when using the system-provided temp directory, it may not 00901 * be possible to atomically rename the resulting file due to cross-device 00902 * issues.) 00903 * 00904 * The file will be deleted according to @a delete_when. 00905 * 00906 * Temporary allocations will be performed in @a scratch_pool. 00907 * 00908 * @since New in 1.6 00909 * @see svn_io_open_unique_file3() 00910 */ 00911 svn_error_t * 00912 svn_stream_open_unique(svn_stream_t **stream, 00913 const char **temp_path, 00914 const char *dirpath, 00915 svn_io_file_del_t delete_when, 00916 apr_pool_t *result_pool, 00917 apr_pool_t *scratch_pool); 00918 00919 00920 /** Create a stream from an APR file. For convenience, if @a file is 00921 * @c NULL, an empty stream created by svn_stream_empty() is returned. 00922 * 00923 * This function should normally be called with @a disown set to FALSE, 00924 * in which case closing the stream will also close the underlying file. 00925 * 00926 * If @a disown is TRUE, the stream will disown the underlying file, 00927 * meaning that svn_stream_close() will not close the file. 00928 * 00929 * @since New in 1.4. 00930 */ 00931 svn_stream_t * 00932 svn_stream_from_aprfile2(apr_file_t *file, 00933 svn_boolean_t disown, 00934 apr_pool_t *pool); 00935 00936 /** Similar to svn_stream_from_aprfile2(), except that the file will 00937 * always be disowned. 00938 * 00939 * @note The stream returned is not considered to "own" the underlying 00940 * file, meaning that svn_stream_close() on the stream will not 00941 * close the file. 00942 * 00943 * @deprecated Provided for backward compatibility with the 1.3 API. 00944 */ 00945 SVN_DEPRECATED 00946 svn_stream_t * 00947 svn_stream_from_aprfile(apr_file_t *file, 00948 apr_pool_t *pool); 00949 00950 /** Set @a *in to a generic stream connected to stdin, allocated in 00951 * @a pool. The stream and its underlying APR handle will be closed 00952 * when @a pool is cleared or destroyed. 00953 * 00954 * @since New in 1.7. 00955 */ 00956 svn_error_t * 00957 svn_stream_for_stdin(svn_stream_t **in, 00958 apr_pool_t *pool); 00959 00960 /** Set @a *err to a generic stream connected to stderr, allocated in 00961 * @a pool. The stream and its underlying APR handle will be closed 00962 * when @a pool is cleared or destroyed. 00963 * 00964 * @since New in 1.7. 00965 */ 00966 svn_error_t * 00967 svn_stream_for_stderr(svn_stream_t **err, 00968 apr_pool_t *pool); 00969 00970 /** Set @a *out to a generic stream connected to stdout, allocated in 00971 * @a pool. The stream and its underlying APR handle will be closed 00972 * when @a pool is cleared or destroyed. 00973 */ 00974 svn_error_t * 00975 svn_stream_for_stdout(svn_stream_t **out, 00976 apr_pool_t *pool); 00977 00978 /** Return a generic stream connected to stringbuf @a str. Allocate the 00979 * stream in @a pool. 00980 */ 00981 svn_stream_t * 00982 svn_stream_from_stringbuf(svn_stringbuf_t *str, 00983 apr_pool_t *pool); 00984 00985 /** Return a generic read-only stream connected to string @a str. 00986 * Allocate the stream in @a pool. 00987 */ 00988 svn_stream_t * 00989 svn_stream_from_string(const svn_string_t *str, 00990 apr_pool_t *pool); 00991 00992 /** Return a stream that decompresses all data read and compresses all 00993 * data written. The stream @a stream is used to read and write all 00994 * compressed data. All compression data structures are allocated on 00995 * @a pool. If compression support is not compiled in then 00996 * svn_stream_compressed() returns @a stream unmodified. Make sure you 00997 * call svn_stream_close() on the stream returned by this function, 00998 * so that all data are flushed and cleaned up. 00999 * 01000 * @note From 1.4, compression support is always compiled in. 01001 */ 01002 svn_stream_t * 01003 svn_stream_compressed(svn_stream_t *stream, 01004 apr_pool_t *pool); 01005 01006 /** Return a stream that calculates checksums for all data read 01007 * and written. The stream @a stream is used to read and write all data. 01008 * The stream and the resulting digests are allocated in @a pool. 01009 * 01010 * When the stream is closed, @a *read_checksum and @a *write_checksum 01011 * are set to point to the resulting checksums, of type @a read_checksum_kind 01012 * and @a write_checksum_kind, respectively. 01013 * 01014 * Both @a read_checksum and @a write_checksum can be @c NULL, in which case 01015 * the respective checksum isn't calculated. 01016 * 01017 * If @a read_all is TRUE, make sure that all data available on @a 01018 * stream is read (and checksummed) when the stream is closed. 01019 * 01020 * Read and write operations can be mixed without interfering. 01021 * 01022 * The @a stream passed into this function is closed when the created 01023 * stream is closed. 01024 * 01025 * @since New in 1.6. 01026 */ 01027 svn_stream_t * 01028 svn_stream_checksummed2(svn_stream_t *stream, 01029 svn_checksum_t **read_checksum, 01030 svn_checksum_t **write_checksum, 01031 svn_checksum_kind_t checksum_kind, 01032 svn_boolean_t read_all, 01033 apr_pool_t *pool); 01034 01035 /** 01036 * Similar to svn_stream_checksummed2(), but always returning the MD5 01037 * checksum in @a read_digest and @a write_digest. 01038 * 01039 * @since New in 1.4. 01040 * @deprecated Provided for backward compatibility with the 1.5 API. 01041 */ 01042 SVN_DEPRECATED 01043 svn_stream_t * 01044 svn_stream_checksummed(svn_stream_t *stream, 01045 const unsigned char **read_digest, 01046 const unsigned char **write_digest, 01047 svn_boolean_t read_all, 01048 apr_pool_t *pool); 01049 01050 /** Read from a generic stream. @see svn_stream_t. */ 01051 svn_error_t * 01052 svn_stream_read(svn_stream_t *stream, 01053 char *buffer, 01054 apr_size_t *len); 01055 01056 /** 01057 * Skip @a len bytes from a generic @a stream. If the stream is exhausted 01058 * before @a len bytes have been read, return an error. 01059 * 01060 * @note No assumption can be made on the semantics of this function 01061 * other than that the stream read pointer will be advanced by *len 01062 * bytes. Depending on the capabilities of the underlying stream 01063 * implementation, this may for instance be translated into a sequence 01064 * of reads or a simple seek operation. If the stream implementation has 01065 * not provided a skip function, this will read from the stream and 01066 * discard the data. 01067 * 01068 * @since New in 1.7. 01069 */ 01070 svn_error_t * 01071 svn_stream_skip(svn_stream_t *stream, 01072 apr_size_t len); 01073 01074 /** Write to a generic stream. @see svn_stream_t. */ 01075 svn_error_t * 01076 svn_stream_write(svn_stream_t *stream, 01077 const char *data, 01078 apr_size_t *len); 01079 01080 /** Close a generic stream. @see svn_stream_t. */ 01081 svn_error_t * 01082 svn_stream_close(svn_stream_t *stream); 01083 01084 /** Reset a generic stream back to its origin. E.g. On a file this would be 01085 * implemented as a seek to position 0). This function returns a 01086 * #SVN_ERR_STREAM_RESET_NOT_SUPPORTED error when the stream doesn't 01087 * implement resetting. 01088 * 01089 * @since New in 1.7. 01090 */ 01091 svn_error_t * 01092 svn_stream_reset(svn_stream_t *stream); 01093 01094 /** Returns @c TRUE if the generic @a stream supports svn_stream_mark(). 01095 * 01096 * @see svn_stream_mark() 01097 * @since New in 1.7. 01098 */ 01099 svn_boolean_t 01100 svn_stream_supports_mark(svn_stream_t *stream); 01101 01102 /** Set a @a mark at the current position of a generic @a stream, 01103 * which can later be sought back to using svn_stream_seek(). 01104 * The @a mark is allocated in @a pool. 01105 * 01106 * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error 01107 * if the stream doesn't implement seeking. 01108 * 01109 * @see svn_stream_seek() 01110 * @since New in 1.7. 01111 */ 01112 svn_error_t * 01113 svn_stream_mark(svn_stream_t *stream, 01114 svn_stream_mark_t **mark, 01115 apr_pool_t *pool); 01116 01117 /** Seek to a @a mark in a generic @a stream. 01118 * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error 01119 * if the stream doesn't implement seeking. Passing NULL as @a mark, 01120 * seeks to the start of the stream. 01121 * 01122 * @see svn_stream_mark() 01123 * @since New in 1.7. 01124 */ 01125 svn_error_t * 01126 svn_stream_seek(svn_stream_t *stream, const svn_stream_mark_t *mark); 01127 01128 /** Return a writable stream which, when written to, writes to both of the 01129 * underlying streams. Both of these streams will be closed upon closure of 01130 * the returned stream; use svn_stream_disown() if this is not the desired 01131 * behavior. One or both of @a out1 and @a out2 may be @c NULL. If both are 01132 * @c NULL, @c NULL is returned. 01133 * 01134 * @since New in 1.7. 01135 */ 01136 svn_stream_t * 01137 svn_stream_tee(svn_stream_t *out1, 01138 svn_stream_t *out2, 01139 apr_pool_t *pool); 01140 01141 01142 /** Write to @a stream using a printf-style @a fmt specifier, passed through 01143 * apr_psprintf() using memory from @a pool. 01144 */ 01145 svn_error_t * 01146 svn_stream_printf(svn_stream_t *stream, 01147 apr_pool_t *pool, 01148 const char *fmt, 01149 ...) 01150 __attribute__((format(printf, 3, 4))); 01151 01152 /** Write to @a stream using a printf-style @a fmt specifier, passed through 01153 * apr_psprintf() using memory from @a pool. The resulting string 01154 * will be translated to @a encoding before it is sent to @a stream. 01155 * 01156 * @note Use @c APR_LOCALE_CHARSET to translate to the encoding of the 01157 * current locale. 01158 * 01159 * @since New in 1.3. 01160 */ 01161 svn_error_t * 01162 svn_stream_printf_from_utf8(svn_stream_t *stream, 01163 const char *encoding, 01164 apr_pool_t *pool, 01165 const char *fmt, 01166 ...) 01167 __attribute__((format(printf, 4, 5))); 01168 01169 /** Allocate @a *stringbuf in @a pool, and read into it one line (terminated 01170 * by @a eol) from @a stream. The line-terminator is read from the stream, 01171 * but is not added to the end of the stringbuf. Instead, the stringbuf 01172 * ends with a usual '\\0'. 01173 * 01174 * If @a stream runs out of bytes before encountering a line-terminator, 01175 * then set @a *eof to @c TRUE, otherwise set @a *eof to FALSE. 01176 */ 01177 svn_error_t * 01178 svn_stream_readline(svn_stream_t *stream, 01179 svn_stringbuf_t **stringbuf, 01180 const char *eol, 01181 svn_boolean_t *eof, 01182 apr_pool_t *pool); 01183 01184 /** 01185 * Read the contents of the readable stream @a from and write them to the 01186 * writable stream @a to calling @a cancel_func before copying each chunk. 01187 * 01188 * @a cancel_func may be @c NULL. 01189 * 01190 * @note both @a from and @a to will be closed upon successful completion of 01191 * the copy (but an error may still be returned, based on trying to close 01192 * the two streams). If the closure is not desired, then you can use 01193 * svn_stream_disown() to protect either or both of the streams from 01194 * being closed. 01195 * 01196 * @since New in 1.6. 01197 */ 01198 svn_error_t * 01199 svn_stream_copy3(svn_stream_t *from, 01200 svn_stream_t *to, 01201 svn_cancel_func_t cancel_func, 01202 void *cancel_baton, 01203 apr_pool_t *pool); 01204 01205 /** 01206 * Same as svn_stream_copy3() but the streams are not closed. 01207 * 01208 * @since New in 1.5. 01209 * @deprecated Provided for backward compatibility with the 1.5 API. 01210 */ 01211 SVN_DEPRECATED 01212 svn_error_t * 01213 svn_stream_copy2(svn_stream_t *from, 01214 svn_stream_t *to, 01215 svn_cancel_func_t cancel_func, 01216 void *cancel_baton, 01217 apr_pool_t *pool); 01218 01219 /** 01220 * Same as svn_stream_copy3(), but without the cancellation function 01221 * or stream closing. 01222 * 01223 * @since New in 1.1. 01224 * @deprecated Provided for backward compatibility with the 1.4 API. 01225 */ 01226 SVN_DEPRECATED 01227 svn_error_t * 01228 svn_stream_copy(svn_stream_t *from, 01229 svn_stream_t *to, 01230 apr_pool_t *pool); 01231 01232 01233 /** Set @a *same to TRUE if @a stream1 and @a stream2 have the same 01234 * contents, else set it to FALSE. 01235 * 01236 * Both streams will be closed before this function returns (regardless of 01237 * the result, or any possible error). 01238 * 01239 * Use @a scratch_pool for temporary allocations. 01240 * 01241 * @since New in 1.7. 01242 */ 01243 svn_error_t * 01244 svn_stream_contents_same2(svn_boolean_t *same, 01245 svn_stream_t *stream1, 01246 svn_stream_t *stream2, 01247 apr_pool_t *pool); 01248 01249 01250 /** 01251 * Same as svn_stream_contents_same2(), but the streams will not be closed. 01252 * 01253 * @since New in 1.4. 01254 * @deprecated Provided for backward compatibility with the 1.6 API. 01255 */ 01256 SVN_DEPRECATED 01257 svn_error_t * 01258 svn_stream_contents_same(svn_boolean_t *same, 01259 svn_stream_t *stream1, 01260 svn_stream_t *stream2, 01261 apr_pool_t *pool); 01262 01263 01264 /** Read the contents of @a stream into memory, returning the data in 01265 * @a result. The stream will be closed when it has been successfully and 01266 * completely read. 01267 * 01268 * The returned memory is allocated in @a result_pool, and any temporary 01269 * allocations are performed in @a scratch_pool. 01270 * 01271 * @note due to memory pseudo-reallocation behavior (due to pools), this 01272 * can be a memory-intensive operation for large files. 01273 * 01274 * @since New in 1.6 01275 */ 01276 svn_error_t * 01277 svn_string_from_stream(svn_string_t **result, 01278 svn_stream_t *stream, 01279 apr_pool_t *result_pool, 01280 apr_pool_t *scratch_pool); 01281 01282 01283 /** @} */ 01284 01285 /** Set @a *result to a string containing the contents of @a 01286 * filename, which is either "-" (indicating that stdin should be 01287 * read) or the utf8-encoded path of a real file. 01288 * 01289 * @warning Callers should be aware of possible unexpected results 01290 * when using this function to read from stdin where additional 01291 * stdin-reading processes abound. For example, if a program tries 01292 * both to invoke an external editor and to read from stdin, stdin 01293 * could be trashed and the editor might act funky or die outright. 01294 * 01295 * @note due to memory pseudo-reallocation behavior (due to pools), this 01296 * can be a memory-intensive operation for large files. 01297 * 01298 * @since New in 1.5. 01299 */ 01300 svn_error_t * 01301 svn_stringbuf_from_file2(svn_stringbuf_t **result, 01302 const char *filename, 01303 apr_pool_t *pool); 01304 01305 /** Similar to svn_stringbuf_from_file2(), except that if @a filename 01306 * is "-", return the error #SVN_ERR_UNSUPPORTED_FEATURE and don't 01307 * touch @a *result. 01308 * 01309 * @deprecated Provided for backwards compatibility with the 1.4 API. 01310 */ 01311 SVN_DEPRECATED 01312 svn_error_t * 01313 svn_stringbuf_from_file(svn_stringbuf_t **result, 01314 const char *filename, 01315 apr_pool_t *pool); 01316 01317 /** Sets @a *result to a string containing the contents of the already opened 01318 * @a file. Reads from the current position in file to the end. Does not 01319 * close the file or reset the cursor position. 01320 * 01321 * @note due to memory pseudo-reallocation behavior (due to pools), this 01322 * can be a memory-intensive operation for large files. 01323 */ 01324 svn_error_t * 01325 svn_stringbuf_from_aprfile(svn_stringbuf_t **result, 01326 apr_file_t *file, 01327 apr_pool_t *pool); 01328 01329 /** Remove file @a path, a utf8-encoded path. This wraps apr_file_remove(), 01330 * converting any error to a Subversion error. If @a ignore_enoent is TRUE, and 01331 * the file is not present (APR_STATUS_IS_ENOENT returns TRUE), then no 01332 * error will be returned. 01333 * 01334 * The file will be removed even if it is not writable. (On Windows and 01335 * OS/2, this function first clears the file's read-only bit.) 01336 * 01337 * @since New in 1.7. 01338 */ 01339 svn_error_t * 01340 svn_io_remove_file2(const char *path, 01341 svn_boolean_t ignore_enoent, 01342 apr_pool_t *scratch_pool); 01343 01344 /** Similar to svn_io_remove_file2(), except with @a ignore_enoent set to FALSE. 01345 * 01346 * @deprecated Provided for backwards compatibility with the 1.6 API. 01347 */ 01348 SVN_DEPRECATED 01349 svn_error_t * 01350 svn_io_remove_file(const char *path, 01351 apr_pool_t *pool); 01352 01353 /** Recursively remove directory @a path. @a path is utf8-encoded. 01354 * If @a ignore_enoent is @c TRUE, don't fail if the target directory 01355 * doesn't exist. Use @a pool for temporary allocations. 01356 * 01357 * Because recursive delete of a directory tree can be a lengthy operation, 01358 * provide @a cancel_func and @a cancel_baton for interruptibility. 01359 * 01360 * @since New in 1.5. 01361 */ 01362 svn_error_t * 01363 svn_io_remove_dir2(const char *path, 01364 svn_boolean_t ignore_enoent, 01365 svn_cancel_func_t cancel_func, 01366 void *cancel_baton, 01367 apr_pool_t *pool); 01368 01369 /** Similar to svn_io_remove_dir2(), but with @a ignore_enoent set to 01370 * @c FALSE and @a cancel_func and @a cancel_baton set to @c NULL. 01371 * 01372 * @deprecated Provided for backward compatibility with the 1.4 API 01373 */ 01374 SVN_DEPRECATED 01375 svn_error_t * 01376 svn_io_remove_dir(const char *path, 01377 apr_pool_t *pool); 01378 01379 /** Read all of the disk entries in directory @a path, a utf8-encoded 01380 * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to 01381 * undefined non-NULL values, allocated in @a pool. 01382 * 01383 * @note The `.' and `..' directories normally returned by 01384 * apr_dir_read() are NOT returned in the hash. 01385 * 01386 * @since New in 1.4. 01387 * @deprecated Provided for backward compatibility with the 1.6 API. 01388 */ 01389 SVN_DEPRECATED 01390 svn_error_t * 01391 svn_io_get_dir_filenames(apr_hash_t **dirents, 01392 const char *path, 01393 apr_pool_t *pool); 01394 01395 /** Read all of the disk entries in directory @a path, a utf8-encoded 01396 * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to 01397 * #svn_io_dirent2_t structures, allocated in @a pool. 01398 * 01399 * If @a only_check_type is set to @c TRUE, only the kind and special 01400 * fields of the svn_io_dirent2_t are filled. 01401 * 01402 * @note The `.' and `..' directories normally returned by 01403 * apr_dir_read() are NOT returned in the hash. 01404 * 01405 * @note The kind field in the @a dirents is set according to the mapping 01406 * as documented for svn_io_check_path(). 01407 * 01408 * @since New in 1.7. 01409 */ 01410 svn_error_t * 01411 svn_io_get_dirents3(apr_hash_t **dirents, 01412 const char *path, 01413 svn_boolean_t only_check_type, 01414 apr_pool_t *result_pool, 01415 apr_pool_t *scratch_pool); 01416 01417 01418 /** Similar to svn_io_get_dirents3, but returns a mapping to svn_io_dirent_t 01419 * structures instead of svn_io_dirent2_t and with only a single pool. 01420 * 01421 * @since New in 1.3. 01422 * @deprecated Provided for backward compatibility with the 1.6 API. 01423 */ 01424 SVN_DEPRECATED 01425 svn_error_t * 01426 svn_io_get_dirents2(apr_hash_t **dirents, 01427 const char *path, 01428 apr_pool_t *pool); 01429 01430 /** Similar to svn_io_get_dirents2(), but @a *dirents is a hash table 01431 * with #svn_node_kind_t values. 01432 * 01433 * @deprecated Provided for backwards compatibility with the 1.2 API. 01434 */ 01435 SVN_DEPRECATED 01436 svn_error_t * 01437 svn_io_get_dirents(apr_hash_t **dirents, 01438 const char *path, 01439 apr_pool_t *pool); 01440 01441 /** Create a svn_io_dirent2_t instance for path. Specialized variant of 01442 * svn_io_stat() that directly translates node_kind and special. 01443 * 01444 * If @a ignore_enoent is set to @c TRUE, set *dirent_p->kind to 01445 * svn_node_none instead of returning an error. 01446 * 01447 * @since New in 1.7. 01448 */ 01449 svn_error_t * 01450 svn_io_stat_dirent(const svn_io_dirent2_t **dirent_p, 01451 const char *path, 01452 svn_boolean_t ignore_enoent, 01453 apr_pool_t *result_pool, 01454 apr_pool_t *scratch_pool); 01455 01456 01457 /** Callback function type for svn_io_dir_walk() */ 01458 typedef svn_error_t * (*svn_io_walk_func_t)(void *baton, 01459 const char *path, 01460 const apr_finfo_t *finfo, 01461 apr_pool_t *pool); 01462 01463 /** Recursively walk the directory rooted at @a dirname, a 01464 * utf8-encoded path, invoking @a walk_func (with @a walk_baton) for 01465 * each item in the tree. For a given directory, invoke @a walk_func 01466 * on the directory itself before invoking it on any children thereof. 01467 * 01468 * Deliver to @a walk_func the information specified by @a wanted, 01469 * which is a combination of @c APR_FINFO_* flags, plus the 01470 * information specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME. 01471 * 01472 * Use @a pool for all allocations. 01473 * 01474 * @note This function does not currently pass all file types to @a 01475 * walk_func -- only APR_DIR, APR_REG, and APR_LNK. We reserve the 01476 * right to pass additional file types through this interface in the 01477 * future, though, so implementations of this callback should 01478 * explicitly test FINFO->filetype. See the APR library's 01479 * apr_filetype_e enum for the various filetypes and their meanings. 01480 * 01481 * @since New in 1.7. 01482 */ 01483 svn_error_t * 01484 svn_io_dir_walk2(const char *dirname, 01485 apr_int32_t wanted, 01486 svn_io_walk_func_t walk_func, 01487 void *walk_baton, 01488 apr_pool_t *pool); 01489 01490 /** Similar to svn_io_dir_walk(), but only calls @a walk_func for 01491 * files of type APR_DIR (directory) and APR_REG (regular file). 01492 * 01493 * @deprecated Provided for backwards compatibility with the 1.6 API. 01494 */ 01495 SVN_DEPRECATED 01496 svn_error_t * 01497 svn_io_dir_walk(const char *dirname, 01498 apr_int32_t wanted, 01499 svn_io_walk_func_t walk_func, 01500 void *walk_baton, 01501 apr_pool_t *pool); 01502 01503 /** 01504 * Start @a cmd with @a args, using utf8-encoded @a path as working 01505 * directory. Return the process handle for the invoked program in @a 01506 * *cmd_proc. 01507 * 01508 * If @a infile_pipe is TRUE, connect @a cmd's stdin to a pipe; 01509 * otherwise, connect it to @a infile (which may be NULL). If 01510 * @a outfile_pipe is TRUE, connect @a cmd's stdout to a pipe; otherwise, 01511 * connect it to @a outfile (which may be NULL). If @a errfile_pipe 01512 * is TRUE, connect @a cmd's stderr to a pipe; otherwise, connect it 01513 * to @a errfile (which may be NULL). (Callers must pass FALSE for 01514 * each of these boolean values for which the corresponding file 01515 * handle is non-NULL.) 01516 * 01517 * @a args is a list of utf8-encoded <tt>const char *</tt> arguments, 01518 * terminated by @c NULL. @a args[0] is the name of the program, though it 01519 * need not be the same as @a cmd. 01520 * 01521 * If @a inherit is TRUE, the invoked program inherits its environment from 01522 * the caller and @a cmd, if not absolute, is searched for in PATH. 01523 * Otherwise, the invoked program runs with an empty environment and @a cmd 01524 * must be an absolute path. 01525 * 01526 * @note On some platforms, failure to execute @a cmd in the child process 01527 * will result in error output being written to @a errfile, if non-NULL, and 01528 * a non-zero exit status being returned to the parent process. 01529 * 01530 * @since New in 1.7. 01531 */ 01532 svn_error_t *svn_io_start_cmd2(apr_proc_t *cmd_proc, 01533 const char *path, 01534 const char *cmd, 01535 const char *const *args, 01536 svn_boolean_t inherit, 01537 svn_boolean_t infile_pipe, 01538 apr_file_t *infile, 01539 svn_boolean_t outfile_pipe, 01540 apr_file_t *outfile, 01541 svn_boolean_t errfile_pipe, 01542 apr_file_t *errfile, 01543 apr_pool_t *pool); 01544 01545 /** 01546 * Similar to svn_io_start_cmd2() but with @a infile_pipe, @a 01547 * outfile_pipe, and @a errfile_pipe always FALSE. 01548 * 01549 * @deprecated Provided for backward compatibility with the 1.6 API 01550 * @since New in 1.3. 01551 */ 01552 SVN_DEPRECATED 01553 svn_error_t * 01554 svn_io_start_cmd(apr_proc_t *cmd_proc, 01555 const char *path, 01556 const char *cmd, 01557 const char *const *args, 01558 svn_boolean_t inherit, 01559 apr_file_t *infile, 01560 apr_file_t *outfile, 01561 apr_file_t *errfile, 01562 apr_pool_t *pool); 01563 01564 /** 01565 * Wait for the process @a *cmd_proc to complete and optionally retrieve 01566 * its exit code. @a cmd is used only in error messages. 01567 * 01568 * If @a exitcode is not NULL, set @a *exitcode to the exit code of the 01569 * process and do not consider any exit code to be an error. If @a exitcode 01570 * is NULL, then if the exit code of the process is non-zero then return an 01571 * #SVN_ERR_EXTERNAL_PROGRAM error. 01572 * 01573 * If @a exitwhy is not NULL, set @a *exitwhy to indicate why the process 01574 * terminated and do not consider any reason to be an error. If @a exitwhy 01575 * is NULL, then if the termination reason is not @c APR_PROC_CHECK_EXIT() 01576 * then return an #SVN_ERR_EXTERNAL_PROGRAM error. 01577 * 01578 * @since New in 1.3. 01579 */ 01580 svn_error_t * 01581 svn_io_wait_for_cmd(apr_proc_t *cmd_proc, 01582 const char *cmd, 01583 int *exitcode, 01584 apr_exit_why_e *exitwhy, 01585 apr_pool_t *pool); 01586 01587 /** Run a command to completion, by first calling svn_io_start_cmd() and 01588 * then calling svn_io_wait_for_cmd(). The parameters correspond to 01589 * the same-named parameters of those two functions. 01590 */ 01591 svn_error_t * 01592 svn_io_run_cmd(const char *path, 01593 const char *cmd, 01594 const char *const *args, 01595 int *exitcode, 01596 apr_exit_why_e *exitwhy, 01597 svn_boolean_t inherit, 01598 apr_file_t *infile, 01599 apr_file_t *outfile, 01600 apr_file_t *errfile, 01601 apr_pool_t *pool); 01602 01603 /** Invoke the configured @c diff program, with @a user_args (an array 01604 * of utf8-encoded @a num_user_args arguments) if they are specified 01605 * (that is, if @a user_args is non-NULL), or "-u" if they are not. 01606 * If @a user_args is NULL, the value of @a num_user_args is ignored. 01607 * 01608 * Diff runs in utf8-encoded @a dir, and its exit status is stored in 01609 * @a exitcode, if it is not @c NULL. 01610 * 01611 * If @a label1 and/or @a label2 are not NULL they will be passed to the diff 01612 * process as the arguments of "-L" options. @a label1 and @a label2 are also 01613 * in utf8, and will be converted to native charset along with the other args. 01614 * 01615 * @a from is the first file passed to diff, and @a to is the second. The 01616 * stdout of diff will be sent to @a outfile, and the stderr to @a errfile. 01617 * 01618 * @a diff_cmd must be non-NULL. 01619 * 01620 * Do all allocation in @a pool. 01621 * @since New in 1.6.0. 01622 */ 01623 svn_error_t * 01624 svn_io_run_diff2(const char *dir, 01625 const char *const *user_args, 01626 int num_user_args, 01627 const char *label1, 01628 const char *label2, 01629 const char *from, 01630 const char *to, 01631 int *exitcode, 01632 apr_file_t *outfile, 01633 apr_file_t *errfile, 01634 const char *diff_cmd, 01635 apr_pool_t *pool); 01636 01637 /** Similar to svn_io_run_diff2() but with @a diff_cmd encoded in internal 01638 * encoding used by APR. 01639 * 01640 * @deprecated Provided for backwards compatibility with the 1.5 API. */ 01641 SVN_DEPRECATED 01642 svn_error_t * 01643 svn_io_run_diff(const char *dir, 01644 const char *const *user_args, 01645 int num_user_args, 01646 const char *label1, 01647 const char *label2, 01648 const char *from, 01649 const char *to, 01650 int *exitcode, 01651 apr_file_t *outfile, 01652 apr_file_t *errfile, 01653 const char *diff_cmd, 01654 apr_pool_t *pool); 01655 01656 01657 01658 /** Invoke the configured @c diff3 program, in utf8-encoded @a dir 01659 * like this: 01660 * 01661 * diff3 -E -m @a mine @a older @a yours > @a merged 01662 * 01663 * (See the diff3 documentation for details.) 01664 * 01665 * If @a user_args is non-NULL, replace "-E" with the <tt>const char*</tt> 01666 * elements that @a user_args contains. 01667 * 01668 * @a mine, @a older and @a yours are utf8-encoded paths (relative to 01669 * @a dir or absolute) to three files that already exist. 01670 * 01671 * @a merged is an open file handle, and is left open after the merge 01672 * result is written to it. (@a merged should *not* be the same file 01673 * as @a mine, or nondeterministic things may happen!) 01674 * 01675 * @a mine_label, @a older_label, @a yours_label are utf8-encoded label 01676 * parameters for diff3's -L option. Any of them may be @c NULL, in 01677 * which case the corresponding @a mine, @a older, or @a yours parameter is 01678 * used instead. 01679 * 01680 * Set @a *exitcode to diff3's exit status. If @a *exitcode is anything 01681 * other than 0 or 1, then return #SVN_ERR_EXTERNAL_PROGRAM. (Note the 01682 * following from the diff3 info pages: "An exit status of 0 means 01683 * `diff3' was successful, 1 means some conflicts were found, and 2 01684 * means trouble.") 01685 * 01686 * @a diff3_cmd must be non-NULL. 01687 * 01688 * Do all allocation in @a pool. 01689 * 01690 * @since New in 1.4. 01691 */ 01692 svn_error_t * 01693 svn_io_run_diff3_3(int *exitcode, 01694 const char *dir, 01695 const char *mine, 01696 const char *older, 01697 const char *yours, 01698 const char *mine_label, 01699 const char *older_label, 01700 const char *yours_label, 01701 apr_file_t *merged, 01702 const char *diff3_cmd, 01703 const apr_array_header_t *user_args, 01704 apr_pool_t *pool); 01705 01706 /** Similar to svn_io_run_diff3_3(), but with @a diff3_cmd encoded in 01707 * internal encoding used by APR. 01708 * 01709 * @deprecated Provided for backwards compatibility with the 1.5 API. 01710 * @since New in 1.4. 01711 */ 01712 SVN_DEPRECATED 01713 svn_error_t * 01714 svn_io_run_diff3_2(int *exitcode, 01715 const char *dir, 01716 const char *mine, 01717 const char *older, 01718 const char *yours, 01719 const char *mine_label, 01720 const char *older_label, 01721 const char *yours_label, 01722 apr_file_t *merged, 01723 const char *diff3_cmd, 01724 const apr_array_header_t *user_args, 01725 apr_pool_t *pool); 01726 01727 /** Similar to svn_io_run_diff3_2(), but with @a user_args set to @c NULL. 01728 * 01729 * @deprecated Provided for backwards compatibility with the 1.3 API. 01730 */ 01731 SVN_DEPRECATED 01732 svn_error_t * 01733 svn_io_run_diff3(const char *dir, 01734 const char *mine, 01735 const char *older, 01736 const char *yours, 01737 const char *mine_label, 01738 const char *older_label, 01739 const char *yours_label, 01740 apr_file_t *merged, 01741 int *exitcode, 01742 const char *diff3_cmd, 01743 apr_pool_t *pool); 01744 01745 01746 /** Parse utf8-encoded @a mimetypes_file as a MIME types file (such as 01747 * is provided with Apache HTTP Server), and set @a *type_map to a 01748 * hash mapping <tt>const char *</tt> filename extensions to 01749 * <tt>const char *</tt> MIME types. 01750 * 01751 * @since New in 1.5. 01752 */ 01753 svn_error_t * 01754 svn_io_parse_mimetypes_file(apr_hash_t **type_map, 01755 const char *mimetypes_file, 01756 apr_pool_t *pool); 01757 01758 01759 /** Examine utf8-encoded @a file to determine if it can be described by a 01760 * known (as in, known by this function) Multipurpose Internet Mail 01761 * Extension (MIME) type. If so, set @a *mimetype to a character string 01762 * describing the MIME type, else set it to @c NULL. 01763 * 01764 * If not @c NULL, @a mimetype_map is a hash mapping <tt>const char *</tt> 01765 * filename extensions to <tt>const char *</tt> MIME types, and is the 01766 * first source consulted regarding @a file's MIME type. 01767 * 01768 * Use @a pool for any necessary allocations. 01769 * 01770 * @since New in 1.5. 01771 */ 01772 svn_error_t * 01773 svn_io_detect_mimetype2(const char **mimetype, 01774 const char *file, 01775 apr_hash_t *mimetype_map, 01776 apr_pool_t *pool); 01777 01778 01779 /** Like svn_io_detect_mimetype2, but with @a mimetypes_map set to 01780 * @c NULL. 01781 * 01782 * @deprecated Provided for backward compatibility with the 1.4 API 01783 */ 01784 SVN_DEPRECATED 01785 svn_error_t * 01786 svn_io_detect_mimetype(const char **mimetype, 01787 const char *file, 01788 apr_pool_t *pool); 01789 01790 01791 /** Examine up to @a len bytes of data in @a buf to determine if the 01792 * can be considered binary data, in which case return TRUE. 01793 * If the data can be considered plain-text data, return FALSE. 01794 * 01795 * @since New in 1.7. 01796 */ 01797 svn_boolean_t 01798 svn_io_is_binary_data(const void *buf, apr_size_t len); 01799 01800 01801 /** Wrapper for apr_file_open(). @a fname is utf8-encoded. */ 01802 svn_error_t * 01803 svn_io_file_open(apr_file_t **new_file, 01804 const char *fname, 01805 apr_int32_t flag, 01806 apr_fileperms_t perm, 01807 apr_pool_t *pool); 01808 01809 01810 /** Wrapper for apr_file_close(). */ 01811 svn_error_t * 01812 svn_io_file_close(apr_file_t *file, 01813 apr_pool_t *pool); 01814 01815 01816 /** Wrapper for apr_file_getc(). */ 01817 svn_error_t * 01818 svn_io_file_getc(char *ch, 01819 apr_file_t *file, 01820 apr_pool_t *pool); 01821 01822 01823 /** Wrapper for apr_file_putc(). 01824 * @since New in 1.7 01825 */ 01826 svn_error_t * 01827 svn_io_file_putc(char ch, 01828 apr_file_t *file, 01829 apr_pool_t *pool); 01830 01831 01832 /** Wrapper for apr_file_info_get(). */ 01833 svn_error_t * 01834 svn_io_file_info_get(apr_finfo_t *finfo, 01835 apr_int32_t wanted, 01836 apr_file_t *file, 01837 apr_pool_t *pool); 01838 01839 01840 /** Wrapper for apr_file_read(). */ 01841 svn_error_t * 01842 svn_io_file_read(apr_file_t *file, 01843 void *buf, 01844 apr_size_t *nbytes, 01845 apr_pool_t *pool); 01846 01847 01848 /** Wrapper for apr_file_read_full(). 01849 * 01850 * If @a hit_eof is not NULL, EOF will be indicated there and no 01851 * svn_error_t error object will be created upon EOF. 01852 * 01853 * @since New in 1.7 01854 */ 01855 svn_error_t * 01856 svn_io_file_read_full2(apr_file_t *file, 01857 void *buf, 01858 apr_size_t nbytes, 01859 apr_size_t *bytes_read, 01860 svn_boolean_t *hit_eof, 01861 apr_pool_t *pool); 01862 01863 01864 /** Similar to svn_io_file_read_full2 with hit_eof being set 01865 * to @c NULL. 01866 * 01867 * @deprecated Provided for backward compatibility with the 1.6 API 01868 */ 01869 SVN_DEPRECATED 01870 svn_error_t * 01871 svn_io_file_read_full(apr_file_t *file, 01872 void *buf, 01873 apr_size_t nbytes, 01874 apr_size_t *bytes_read, 01875 apr_pool_t *pool); 01876 01877 01878 /** Wrapper for apr_file_seek(). */ 01879 svn_error_t * 01880 svn_io_file_seek(apr_file_t *file, 01881 apr_seek_where_t where, 01882 apr_off_t *offset, 01883 apr_pool_t *pool); 01884 01885 01886 /** Wrapper for apr_file_write(). */ 01887 svn_error_t * 01888 svn_io_file_write(apr_file_t *file, 01889 const void *buf, 01890 apr_size_t *nbytes, 01891 apr_pool_t *pool); 01892 01893 01894 /** Wrapper for apr_file_write_full(). */ 01895 svn_error_t * 01896 svn_io_file_write_full(apr_file_t *file, 01897 const void *buf, 01898 apr_size_t nbytes, 01899 apr_size_t *bytes_written, 01900 apr_pool_t *pool); 01901 01902 /** 01903 * Open a unique file in @a dirpath, and write @a nbytes from @a buf to 01904 * the file before flushing it to disk and closing it. Return the name 01905 * of the newly created file in @a *tmp_path, allocated in @a pool. 01906 * 01907 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir(). 01908 * (Note that when using the system-provided temp directory, it may not 01909 * be possible to atomically rename the resulting file due to cross-device 01910 * issues.) 01911 * 01912 * The file will be deleted according to @a delete_when. 01913 * 01914 * @since New in 1.6. 01915 */ 01916 svn_error_t * 01917 svn_io_write_unique(const char **tmp_path, 01918 const char *dirpath, 01919 const void *buf, 01920 apr_size_t nbytes, 01921 svn_io_file_del_t delete_when, 01922 apr_pool_t *pool); 01923 01924 /** Wrapper for apr_file_trunc(). 01925 * @since New in 1.6. */ 01926 svn_error_t * 01927 svn_io_file_trunc(apr_file_t *file, 01928 apr_off_t offset, 01929 apr_pool_t *pool); 01930 01931 01932 /** Wrapper for apr_stat(). @a fname is utf8-encoded. */ 01933 svn_error_t * 01934 svn_io_stat(apr_finfo_t *finfo, 01935 const char *fname, 01936 apr_int32_t wanted, 01937 apr_pool_t *pool); 01938 01939 01940 /** Rename and/or move the node (not necessarily a regular file) at 01941 * @a from_path to a new path @a to_path within the same filesystem. 01942 * In some cases, an existing node at @a to_path will be overwritten. 01943 * 01944 * A wrapper for apr_file_rename(). @a from_path and @a to_path are 01945 * utf8-encoded. 01946 */ 01947 svn_error_t * 01948 svn_io_file_rename(const char *from_path, 01949 const char *to_path, 01950 apr_pool_t *pool); 01951 01952 01953 /** Move the file from @a from_path to @a to_path, even across device 01954 * boundaries. Overwrite @a to_path if it exists. 01955 * 01956 * @note This function is different from svn_io_file_rename in that the 01957 * latter fails in the 'across device boundaries' case. 01958 * 01959 * @since New in 1.3. 01960 */ 01961 svn_error_t * 01962 svn_io_file_move(const char *from_path, 01963 const char *to_path, 01964 apr_pool_t *pool); 01965 01966 01967 /** Wrapper for apr_dir_make(). @a path is utf8-encoded. */ 01968 svn_error_t * 01969 svn_io_dir_make(const char *path, 01970 apr_fileperms_t perm, 01971 apr_pool_t *pool); 01972 01973 /** Same as svn_io_dir_make(), but sets the hidden attribute on the 01974 directory on systems that support it. */ 01975 svn_error_t * 01976 svn_io_dir_make_hidden(const char *path, 01977 apr_fileperms_t perm, 01978 apr_pool_t *pool); 01979 01980 /** 01981 * Same as svn_io_dir_make(), but attempts to set the sgid on the 01982 * directory on systems that support it. Does not return an error if 01983 * the attempt to set the sgid bit fails. On Unix filesystems, 01984 * setting the sgid bit on a directory ensures that files and 01985 * subdirectories created within inherit group ownership from the 01986 * parent instead of from the primary gid. 01987 * 01988 * @since New in 1.1. 01989 */ 01990 svn_error_t * 01991 svn_io_dir_make_sgid(const char *path, 01992 apr_fileperms_t perm, 01993 apr_pool_t *pool); 01994 01995 /** Wrapper for apr_dir_open(). @a dirname is utf8-encoded. */ 01996 svn_error_t * 01997 svn_io_dir_open(apr_dir_t **new_dir, 01998 const char *dirname, 01999 apr_pool_t *pool); 02000 02001 /** Wrapper for apr_dir_close(). 02002 * 02003 * @since New in 1.7. 02004 */ 02005 svn_error_t * 02006 svn_io_dir_close(apr_dir_t *thedir); 02007 02008 /** Wrapper for apr_dir_remove(). @a dirname is utf8-encoded. 02009 * @note This function has this name to avoid confusion with 02010 * svn_io_remove_dir2(), which is recursive. 02011 */ 02012 svn_error_t * 02013 svn_io_dir_remove_nonrecursive(const char *dirname, 02014 apr_pool_t *pool); 02015 02016 02017 /** Wrapper for apr_dir_read(). Ensures that @a finfo->name is 02018 * utf8-encoded, which means allocating @a finfo->name in @a pool, 02019 * which may or may not be the same as @a finfo's pool. Use @a pool 02020 * for error allocation as well. 02021 */ 02022 svn_error_t * 02023 svn_io_dir_read(apr_finfo_t *finfo, 02024 apr_int32_t wanted, 02025 apr_dir_t *thedir, 02026 apr_pool_t *pool); 02027 02028 /** Wrapper for apr_file_name_get(). @a *filename is utf8-encoded. 02029 * 02030 * @note The file name may be NULL. 02031 * 02032 * @since New in 1.7. */ 02033 svn_error_t * 02034 svn_io_file_name_get(const char **filename, 02035 apr_file_t *file, 02036 apr_pool_t *pool); 02037 02038 02039 02040 /** Version/format files. 02041 * 02042 * @defgroup svn_io_format_files Version/format files 02043 * @{ 02044 */ 02045 02046 /** Set @a *version to the integer that starts the file at @a path. If the 02047 * file does not begin with a series of digits followed by a newline, 02048 * return the error #SVN_ERR_BAD_VERSION_FILE_FORMAT. Use @a pool for 02049 * all allocations. 02050 */ 02051 svn_error_t * 02052 svn_io_read_version_file(int *version, 02053 const char *path, 02054 apr_pool_t *pool); 02055 02056 /** Create (or overwrite) the file at @a path with new contents, 02057 * formatted as a non-negative integer @a version followed by a single 02058 * newline. On successful completion the file will be read-only. Use 02059 * @a pool for all allocations. 02060 */ 02061 svn_error_t * 02062 svn_io_write_version_file(const char *path, 02063 int version, 02064 apr_pool_t *pool); 02065 02066 /** @} */ 02067 02068 #ifdef __cplusplus 02069 } 02070 #endif /* __cplusplus */ 02071 02072 #endif /* SVN_IO_H */