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