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