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