00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2004 CollabNet. All rights reserved. 00005 * 00006 * This software is licensed as described in the file COPYING, which 00007 * you should have received as part of this distribution. The terms 00008 * are also available at http://subversion.tigris.org/license-1.html. 00009 * If newer versions of this license are posted there, you may use a 00010 * newer version instead, at your option. 00011 * 00012 * This software consists of voluntary contributions made by many 00013 * individuals. For exact contribution history, see the revision 00014 * history and logs, available at http://subversion.tigris.org/. 00015 * ==================================================================== 00016 * @endcopyright 00017 * 00018 * @file svn_io.h 00019 * @brief General file I/O for Subversion 00020 */ 00021 00022 /* ==================================================================== */ 00023 00024 00025 #ifndef SVN_IO_H 00026 #define SVN_IO_H 00027 00028 #include <apr.h> 00029 #include <apr_pools.h> 00030 #include <apr_file_io.h> 00031 #include <apr_thread_proc.h> 00032 00033 #include "svn_types.h" 00034 #include "svn_error.h" 00035 #include "svn_string.h" 00036 00037 #ifdef __cplusplus 00038 extern "C" { 00039 #endif /* __cplusplus */ 00040 00041 00042 00043 /** Represents the kind and special status of a directory entry. 00044 * 00045 * @since New in 1.3. 00046 */ 00047 typedef struct svn_io_dirent_t { 00048 /** The kind of this entry. */ 00049 svn_node_kind_t kind; 00050 /** If @c kind is @c svn_node_file, whether this entry is a special file; 00051 * else false. 00052 * 00053 * @see svn_io_check_special_path(). 00054 */ 00055 svn_boolean_t special; 00056 } svn_io_dirent_t; 00057 00058 /** Determine the @a kind of @a path. 00059 * 00060 * If utf8-encoded @a path exists, set @a *kind to the appropriate kind, 00061 * else set it to @c svn_node_unknown. 00062 * 00063 * If @a path is a file, @a *kind is set to @c svn_node_file. 00064 * 00065 * If @a path is a directory, @a *kind is set to @c svn_node_dir. 00066 * 00067 * If @a path does not exist in its final component, @a *kind is set to 00068 * @c svn_node_none. 00069 * 00070 * If intermediate directories on the way to @a path don't exist, an 00071 * error is returned, and @a *kind's value is undefined. 00072 */ 00073 svn_error_t *svn_io_check_path (const char *path, 00074 svn_node_kind_t *kind, 00075 apr_pool_t *pool); 00076 00077 /** 00078 * Like svn_io_check_path(), but also set *is_special to @c TRUE if 00079 * the path is not a normal file. 00080 * 00081 * @since New in 1.1. 00082 */ 00083 svn_error_t *svn_io_check_special_path (const char *path, 00084 svn_node_kind_t *kind, 00085 svn_boolean_t *is_special, 00086 apr_pool_t *pool); 00087 00088 /** Like svn_io_check_path(), but resolve symlinks. This returns the 00089 same varieties of @a kind as svn_io_check_path(). */ 00090 svn_error_t *svn_io_check_resolved_path (const char *path, 00091 svn_node_kind_t *kind, 00092 apr_pool_t *pool); 00093 00094 00095 /** Open a new file (for writing) with a unique name based on utf-8 00096 * encoded @a path, in the same directory as @a path. The file handle is 00097 * returned in @a *f, and the name, which ends with @a suffix, is returned 00098 * in @a *unique_name_p, also utf8-encoded. If @a delete_on_close is set, 00099 * then the @c APR_DELONCLOSE flag will be used when opening the file. The 00100 * @c APR_BUFFERED flag will always be used. 00101 * 00102 * The first attempt will just append @a suffix. If the result is not 00103 * a unique name, then subsequent attempts will append a dot, 00104 * followed by an iteration number ("2", then "3", and so on), 00105 * followed by the suffix. For example, if @a path is 00106 * 00107 * tests/t1/A/D/G/pi 00108 * 00109 * then successive calls to 00110 * 00111 * svn_io_open_unique_file(&f, &unique_name, @a path, ".tmp", pool) 00112 * 00113 * will open 00114 * 00115 * tests/t1/A/D/G/pi.tmp 00116 * tests/t1/A/D/G/pi.2.tmp 00117 * tests/t1/A/D/G/pi.3.tmp 00118 * tests/t1/A/D/G/pi.4.tmp 00119 * tests/t1/A/D/G/pi.5.tmp 00120 * ... 00121 * 00122 * @a *unique_name_p will never be exactly the same as @a path, even 00123 * if @a path does not exist. 00124 * 00125 * It doesn't matter if @a path is a file or directory, the unique name will 00126 * be in @a path's parent either way. 00127 * 00128 * Allocate @a *f and @a *unique_name_p in @a pool. 00129 * 00130 * If no unique name can be found, @c SVN_ERR_IO_UNIQUE_NAMES_EXHAUSTED is 00131 * the error returned. 00132 * 00133 * Claim of Historical Inevitability: this function was written 00134 * because 00135 * 00136 * - tmpnam() is not thread-safe. 00137 * - tempname() tries standard system tmp areas first. 00138 */ 00139 svn_error_t *svn_io_open_unique_file (apr_file_t **f, 00140 const char **unique_name_p, 00141 const char *path, 00142 const char *suffix, 00143 svn_boolean_t delete_on_close, 00144 apr_pool_t *pool); 00145 00146 /** 00147 * Like svn_io_open_unique_file(), except that instead of creating a 00148 * file, a symlink is generated that references the path @a dest. 00149 * 00150 * @since New in 1.1. 00151 */ 00152 svn_error_t *svn_io_create_unique_link (const char **unique_name_p, 00153 const char *path, 00154 const char *dest, 00155 const char *suffix, 00156 apr_pool_t *pool); 00157 00158 00159 /** 00160 * Set @a *dest to the path that the symlink at @a path references. 00161 * Allocate the string from @a pool. 00162 * 00163 * @since New in 1.1. 00164 */ 00165 svn_error_t *svn_io_read_link (svn_string_t **dest, 00166 const char *path, 00167 apr_pool_t *pool); 00168 00169 00170 /** Set @a *dir to a directory path (allocated in @a pool) deemed 00171 * usable for the creation of temporary files and subdirectories. 00172 */ 00173 svn_error_t *svn_io_temp_dir (const char **dir, 00174 apr_pool_t *pool); 00175 00176 00177 /** Copy @a src to @a dst atomically. Overwrite @a dst if it exists, else 00178 * create it. Both @a src and @a dst are utf8-encoded filenames. If 00179 * @a copy_perms is true, set @a dst's permissions to match those of @a src. 00180 */ 00181 svn_error_t *svn_io_copy_file (const char *src, 00182 const char *dst, 00183 svn_boolean_t copy_perms, 00184 apr_pool_t *pool); 00185 00186 /** 00187 * Copy symbolic link @a src to @a dst atomically. Overwrite @a dst 00188 * if it exists, else create it. Both @a src and @a dst are 00189 * utf8-encoded filenames. After copying, the @a dst link will point 00190 * to the same thing @a src does. 00191 * 00192 * @since New in 1.1. 00193 */ 00194 svn_error_t *svn_io_copy_link (const char *src, 00195 const char *dst, 00196 apr_pool_t *pool); 00197 00198 00199 /** Recursively copy directory @a src into @a dst_parent, as a new entry named 00200 * @a dst_basename. If @a dst_basename already exists in @a dst_parent, 00201 * return error. @a copy_perms will be passed through to svn_io_copy_file() 00202 * when any files are copied. @a src, @a dst_parent, and @a dst_basename are 00203 * all utf8-encoded. 00204 * 00205 * If @a cancel_func is non-null, invoke it with @a cancel_baton at 00206 * various points during the operation. If it returns any error 00207 * (typically @c SVN_ERR_CANCELLED), return that error immediately. 00208 */ 00209 svn_error_t *svn_io_copy_dir_recursively (const char *src, 00210 const char *dst_parent, 00211 const char *dst_basename, 00212 svn_boolean_t copy_perms, 00213 svn_cancel_func_t cancel_func, 00214 void *cancel_baton, 00215 apr_pool_t *pool); 00216 00217 00218 00219 /** Create directory @a path on the file system, creating intermediate 00220 * directories as required, like <tt>mkdir -p</tt>. Report no error if @a 00221 * path already exists. @a path is utf8-encoded. 00222 * 00223 * This is essentially a wrapper for apr_dir_make_recursive(), passing 00224 * @c APR_OS_DEFAULT as the permissions. 00225 */ 00226 svn_error_t *svn_io_make_dir_recursively (const char *path, apr_pool_t *pool); 00227 00228 00229 /** Set @a *is_empty_p to @c TRUE if directory @a path is empty, else to 00230 * @c FALSE if it is not empty. @a path must be a directory, and is 00231 * utf8-encoded. Use @a pool for temporary allocation. 00232 */ 00233 svn_error_t * 00234 svn_io_dir_empty (svn_boolean_t *is_empty_p, 00235 const char *path, 00236 apr_pool_t *pool); 00237 00238 00239 /** Append @a src to @a dst. @a dst will be appended to if it exists, else it 00240 * will be created. Both @a src and @a dst are utf8-encoded. 00241 */ 00242 svn_error_t *svn_io_append_file (const char *src, 00243 const char *dst, 00244 apr_pool_t *pool); 00245 00246 00247 /** Make a file as read-only as the operating system allows. 00248 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is 00249 * @c TRUE, don't fail if the target file doesn't exist. 00250 */ 00251 svn_error_t *svn_io_set_file_read_only (const char *path, 00252 svn_boolean_t ignore_enoent, 00253 apr_pool_t *pool); 00254 00255 00256 /** Make a file as writable as the operating system allows. 00257 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is 00258 * @c TRUE, don't fail if the target file doesn't exist. 00259 * @warning On Unix this function will do the equivalent of chmod a+w path. 00260 * If this is not what you want you should not use this function, but rather 00261 * use apr_file_perms_set(). 00262 */ 00263 svn_error_t *svn_io_set_file_read_write (const char *path, 00264 svn_boolean_t ignore_enoent, 00265 apr_pool_t *pool); 00266 00267 00268 /** Minimally change the read-write permissions of a file. 00269 * @since New in 1.1. 00270 * 00271 * When making @a path read-write on operating systems with unix style 00272 * permissions, set the permissions on @a path to the permissions that 00273 * are set when a new file is created (effectively honoring the user's 00274 * umask). 00275 * 00276 * When making the file read-only on operating systems with unix style 00277 * permissions, remove all write permissions. 00278 * 00279 * On other operating systems, toggle the file's "writability" as much as 00280 * the operating system allows. 00281 * 00282 * @a path is the utf8-encoded path to the file. If @a enable_write 00283 * is @c TRUE, then make the file read-write. If @c FALSE, make it 00284 * write-only. If @a ignore_enoent is @c TRUE, don't fail if the target 00285 * file doesn't exist. 00286 */ 00287 svn_error_t *svn_io_set_file_read_write_carefully (const char *path, 00288 svn_boolean_t enable_write, 00289 svn_boolean_t ignore_enoent, 00290 apr_pool_t *pool); 00291 00292 /** Toggle a file's "executability". 00293 * 00294 * When making the file executable on operating systems with unix style 00295 * permissions, never add an execute permission where there is not 00296 * already a read permission: that is, only make the file executable 00297 * for the user, group or world if the corresponding read permission 00298 * is already set for user, group or world. 00299 * 00300 * When making the file non-executable on operating systems with unix style 00301 * permissions, remove all execute permissions. 00302 * 00303 * On other operating systems, toggle the file's "executability" as much as 00304 * the operating system allows. 00305 * 00306 * @a path is the utf8-encoded path to the file. If @a executable 00307 * is @c TRUE, then make the file executable. If @c FALSE, make in 00308 * non-executable. If @a ignore_enoent is @c TRUE, don't fail if the target 00309 * file doesn't exist. 00310 */ 00311 svn_error_t *svn_io_set_file_executable (const char *path, 00312 svn_boolean_t executable, 00313 svn_boolean_t ignore_enoent, 00314 apr_pool_t *pool); 00315 00316 /** Determine whether a file is executable by the current user. 00317 * Set @a *executable to @c TRUE if the file @a path is executable by the 00318 * current user, otherwise set it to @c FALSE. 00319 * 00320 * On Windows and on platforms without userids, always returns @c FALSE. 00321 */ 00322 svn_error_t *svn_io_is_file_executable(svn_boolean_t *executable, 00323 const char *path, 00324 apr_pool_t *pool); 00325 00326 00327 /** Read a line from @a file into @a buf, but not exceeding @a *limit bytes. 00328 * Does not include newline, instead '\\0' is put there. 00329 * Length (as in strlen) is returned in @a *limit. 00330 * @a buf should be pre-allocated. 00331 * @a file should be already opened. 00332 * 00333 * When the file is out of lines, @c APR_EOF will be returned. 00334 */ 00335 svn_error_t * 00336 svn_io_read_length_line (apr_file_t *file, char *buf, apr_size_t *limit, 00337 apr_pool_t *pool); 00338 00339 00340 /** Set @a *apr_time to the time of last modification of the contents of the 00341 * file @a path. @a path is utf8-encoded. 00342 * 00343 * @note This is the APR mtime which corresponds to the traditional mtime 00344 * on Unix, and the last write time on Windows. 00345 */ 00346 svn_error_t *svn_io_file_affected_time (apr_time_t *apr_time, 00347 const char *path, 00348 apr_pool_t *pool); 00349 00350 /** Set the timestamp of file @a path to @a apr_time. @a path is 00351 * utf8-encoded. 00352 * 00353 * @note This is the APR mtime which corresponds to the traditional mtime 00354 * on Unix, and the last write time on Windows. 00355 */ 00356 svn_error_t *svn_io_set_file_affected_time (apr_time_t apr_time, 00357 const char *path, 00358 apr_pool_t *pool); 00359 00360 00361 00362 /** Set @a *different_p to non-zero if @a file1 and @a file2 have different 00363 * sizes, else set to zero. Both @a file1 and @a file2 are utf8-encoded. 00364 * 00365 * Setting @a *different_p to zero does not mean the files definitely 00366 * have the same size, it merely means that the sizes are not 00367 * definitely different. That is, if the size of one or both files 00368 * cannot be determined, then the sizes are not known to be different, 00369 * so @a *different_p is set to 0. 00370 */ 00371 svn_error_t *svn_io_filesizes_different_p (svn_boolean_t *different_p, 00372 const char *file1, 00373 const char *file2, 00374 apr_pool_t *pool); 00375 00376 00377 /** Put the md5 checksum of @a file into @a digest. 00378 * @a digest points to @c APR_MD5_DIGESTSIZE bytes of storage. 00379 * Use @a pool only for temporary allocations. 00380 */ 00381 svn_error_t *svn_io_file_checksum (unsigned char digest[], 00382 const char *file, 00383 apr_pool_t *pool); 00384 00385 00386 /** Set @a *same to non-zero if @a file1 and @a file2 have the same 00387 * contents, else set it to zero. Use @a pool for temporary allocations. 00388 */ 00389 svn_error_t *svn_io_files_contents_same_p (svn_boolean_t *same, 00390 const char *file1, 00391 const char *file2, 00392 apr_pool_t *pool); 00393 00394 /** Create file at @a file with contents @a contents. 00395 * will be created. Path @a file is utf8-encoded. 00396 * Use @a pool for memory allocations. 00397 */ 00398 svn_error_t *svn_io_file_create (const char *file, 00399 const char *contents, 00400 apr_pool_t *pool); 00401 00402 /** 00403 * Lock file at @a lock_file. If @a exclusive is TRUE, 00404 * obtain exclusive lock, otherwise obtain shared lock. 00405 * Lock will be automatically released when @a pool is cleared or destroyed. 00406 * Use @a pool for memory allocations. 00407 * 00408 * @deprecated Provided for backward compatibility with the 1.0 API. 00409 */ 00410 svn_error_t *svn_io_file_lock (const char *lock_file, 00411 svn_boolean_t exclusive, 00412 apr_pool_t *pool); 00413 00414 /** 00415 * Lock file at @a lock_file. If @a exclusive is TRUE, 00416 * obtain exclusive lock, otherwise obtain shared lock. 00417 * 00418 * If @a nonblocking is TRUE, do not wait for the lock if it 00419 * is not available: throw an error instead. 00420 * 00421 * Lock will be automatically released when @a pool is cleared or destroyed. 00422 * Use @a pool for memory allocations. 00423 * 00424 * @since New in 1.1. 00425 */ 00426 svn_error_t *svn_io_file_lock2 (const char *lock_file, 00427 svn_boolean_t exclusive, 00428 svn_boolean_t nonblocking, 00429 apr_pool_t *pool); 00430 /** 00431 * Flush any unwritten data from @a file to disk. Use @a pool for 00432 * memory allocations. 00433 * 00434 * @since New in 1.1. 00435 */ 00436 svn_error_t *svn_io_file_flush_to_disk (apr_file_t *file, 00437 apr_pool_t *pool); 00438 00439 /** Copy file @a file from location @a src_path to location @a dest_path. 00440 * Use @a pool for memory allocations. 00441 */ 00442 svn_error_t *svn_io_dir_file_copy (const char *src_path, 00443 const char *dest_path, 00444 const char *file, 00445 apr_pool_t *pool); 00446 00447 00448 /** Generic byte-streams 00449 * 00450 * @defgroup svn_io_byte_streams generic byte streams 00451 * @{ 00452 */ 00453 00454 /** An abstract stream of bytes--either incoming or outgoing or both. 00455 * 00456 * The creator of a stream sets functions to handle read and write. 00457 * Both of these handlers accept a baton whose value is determined at 00458 * stream creation time; this baton can point to a structure 00459 * containing data associated with the stream. If a caller attempts 00460 * to invoke a handler which has not been set, it will generate a 00461 * runtime assertion failure. The creator can also set a handler for 00462 * close requests so that it can flush buffered data or whatever; 00463 * if a close handler is not specified, a close request on the stream 00464 * will simply be ignored. Note that svn_stream_close() does not 00465 * deallocate the memory used to allocate the stream structure; free 00466 * the pool you created the stream in to free that memory. 00467 * 00468 * The read and write handlers accept length arguments via pointer. 00469 * On entry to the handler, the pointed-to value should be the amount 00470 * of data which can be read or the amount of data to write. When the 00471 * handler returns, the value is reset to the amount of data actually 00472 * read or written. Handlers are obliged to complete a read or write 00473 * to the maximum extent possible; thus, a short read with no 00474 * associated error implies the end of the input stream, and a short 00475 * write should never occur without an associated error. 00476 */ 00477 typedef struct svn_stream_t svn_stream_t; 00478 00479 00480 00481 /** Read handler function for a generic stream. */ 00482 typedef svn_error_t *(*svn_read_fn_t) (void *baton, 00483 char *buffer, 00484 apr_size_t *len); 00485 00486 /** Write handler function for a generic stream. */ 00487 typedef svn_error_t *(*svn_write_fn_t) (void *baton, 00488 const char *data, 00489 apr_size_t *len); 00490 00491 /** Close handler function for a generic stream. */ 00492 typedef svn_error_t *(*svn_close_fn_t) (void *baton); 00493 00494 00495 /** Creating a generic stream. */ 00496 svn_stream_t *svn_stream_create (void *baton, apr_pool_t *pool); 00497 00498 /** Set @a stream's baton to @a baton */ 00499 void svn_stream_set_baton (svn_stream_t *stream, void *baton); 00500 00501 /** Set @a stream's read function to @a read_fn */ 00502 void svn_stream_set_read (svn_stream_t *stream, svn_read_fn_t read_fn); 00503 00504 /** Set @a stream's write function to @a write_fn */ 00505 void svn_stream_set_write (svn_stream_t *stream, svn_write_fn_t write_fn); 00506 00507 /** Set @a stream's close function to @a close_fn */ 00508 void svn_stream_set_close (svn_stream_t *stream, svn_close_fn_t close_fn); 00509 00510 00511 /** Convenience function to create a generic stream which is empty. */ 00512 svn_stream_t *svn_stream_empty (apr_pool_t *pool); 00513 00514 00515 /** Convenience function for creating streams which operate on APR 00516 * files. For convenience, if @a file is NULL then svn_stream_empty(pool) 00517 * is returned. Note that the stream returned by these operations is not 00518 * considered to "own" the underlying file, meaning that svn_stream_close() 00519 * on the stream will not close the file. 00520 */ 00521 svn_stream_t *svn_stream_from_aprfile (apr_file_t *file, apr_pool_t *pool); 00522 00523 /** Set @a *out to a generic stream connected to stdout, allocated in 00524 * @a pool. The stream and its underlying APR handle will be closed 00525 * when @a pool is cleared or destroyed. 00526 */ 00527 svn_error_t *svn_stream_for_stdout (svn_stream_t **out, apr_pool_t *pool); 00528 00529 /** Return a generic stream connected to stringbuf @a str. Allocate the 00530 * stream in @a pool. 00531 */ 00532 svn_stream_t *svn_stream_from_stringbuf (svn_stringbuf_t *str, 00533 apr_pool_t *pool); 00534 00535 /** Return a stream that decompresses all data read and compresses all 00536 * data written. The stream @a stream is used to read and write all 00537 * compressed data. All compression data structures are allocated on 00538 * @a pool. If compression support is not compiled in then 00539 * svn_stream_compressed() returns @a stream unmodified. Make sure you 00540 * call svn_stream_close() on the stream returned by this function, 00541 * so that all data are flushed and cleaned up. 00542 */ 00543 svn_stream_t *svn_stream_compressed (svn_stream_t *stream, 00544 apr_pool_t *pool); 00545 00546 /** Read from a generic stream. */ 00547 svn_error_t *svn_stream_read (svn_stream_t *stream, char *buffer, 00548 apr_size_t *len); 00549 00550 /** Write to a generic stream. */ 00551 svn_error_t *svn_stream_write (svn_stream_t *stream, const char *data, 00552 apr_size_t *len); 00553 00554 /** Close a generic stream. */ 00555 svn_error_t *svn_stream_close (svn_stream_t *stream); 00556 00557 00558 /** Write to @a stream using a printf-style @a fmt specifier, passed through 00559 * apr_psprintf() using memory from @a pool. 00560 */ 00561 svn_error_t *svn_stream_printf (svn_stream_t *stream, 00562 apr_pool_t *pool, 00563 const char *fmt, 00564 ...) 00565 __attribute__ ((format(printf, 3, 4))); 00566 00567 /** Write to @a stream using a printf-style @a fmt specifier, passed through 00568 * apr_psprintf() using memory from @a pool. The resulting string 00569 * will be translated to @a encoding before it is sent to @a stream. 00570 * 00571 * @note Use @c APR_LOCALE_CHARSET to translate to the encoding of the 00572 * current locale. 00573 * 00574 * @since New in 1.3. 00575 */ 00576 svn_error_t *svn_stream_printf_from_utf8 (svn_stream_t *stream, 00577 const char *encoding, 00578 apr_pool_t *pool, 00579 const char *fmt, 00580 ...) 00581 __attribute__ ((format(printf, 4, 5))); 00582 00583 /** Allocate @a *stringbuf in @a pool, and read into it one line (terminated 00584 * by @a eol) from @a stream. The line-terminator is read from the stream, 00585 * but is not added to the end of the stringbuf. Instead, the stringbuf 00586 * ends with a usual '\\0'. 00587 * 00588 * If @a stream runs out of bytes before encountering a line-terminator, 00589 * then set @a *eof to @c TRUE, otherwise set @a *eof to FALSE. 00590 */ 00591 svn_error_t * 00592 svn_stream_readline (svn_stream_t *stream, 00593 svn_stringbuf_t **stringbuf, 00594 const char *eol, 00595 svn_boolean_t *eof, 00596 apr_pool_t *pool); 00597 00598 /** 00599 * Read the contents of the readable stream @a from and write them to the 00600 * writable stream @a to. 00601 * 00602 * @since New in 1.1. 00603 */ 00604 svn_error_t *svn_stream_copy (svn_stream_t *from, svn_stream_t *to, 00605 apr_pool_t *pool); 00606 00607 /** @} */ 00608 00609 /** Sets @a *result to a string containing the contents of @a filename, a 00610 * utf8-encoded path. 00611 * 00612 * If @a filename is "-", return the error @c SVN_ERR_UNSUPPORTED_FEATURE 00613 * and don't touch @a *result. 00614 * 00615 * ### Someday, "-" will fill @a *result from stdin. The problem right 00616 * now is that if the same command invokes the editor, stdin is crap, 00617 * and the editor acts funny or dies outright. One solution is to 00618 * disallow stdin reading and invoking the editor, but how to do that 00619 * reliably? 00620 */ 00621 svn_error_t *svn_stringbuf_from_file (svn_stringbuf_t **result, 00622 const char *filename, 00623 apr_pool_t *pool); 00624 00625 /** Sets @a *result to a string containing the contents of the already opened 00626 * @a file. Reads from the current position in file to the end. Does not 00627 * close the file or reset the cursor position. 00628 */ 00629 svn_error_t *svn_stringbuf_from_aprfile (svn_stringbuf_t **result, 00630 apr_file_t *file, 00631 apr_pool_t *pool); 00632 00633 /** Remove file @a path, a utf8-encoded path. This wraps apr_file_remove(), 00634 * converting any error to a Subversion error. 00635 */ 00636 svn_error_t *svn_io_remove_file (const char *path, apr_pool_t *pool); 00637 00638 /** Recursively remove directory @a path. @a path is utf8-encoded. */ 00639 svn_error_t *svn_io_remove_dir (const char *path, apr_pool_t *pool); 00640 00641 00642 /** Read all of the disk entries in directory @a path, a utf8-encoded 00643 * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to 00644 * @c svn_io_dirent_t structures, allocated in @a pool. 00645 * 00646 * @note The `.' and `..' directories normally returned by 00647 * apr_dir_read() are NOT returned in the hash. 00648 * 00649 * @since New in 1.3. 00650 */ 00651 svn_error_t *svn_io_get_dirents2 (apr_hash_t **dirents, 00652 const char *path, 00653 apr_pool_t *pool); 00654 00655 /** similar to svn_io_get_dirents2(), but *DIRENTS is a hash table 00656 * with @c svn_node_kind_t values. 00657 * 00658 * @deprecated Provided for backwards compatibility with the 1.2 API. 00659 */ 00660 svn_error_t *svn_io_get_dirents (apr_hash_t **dirents, 00661 const char *path, 00662 apr_pool_t *pool); 00663 00664 00665 /** Callback function type for svn_io_dir_walk() */ 00666 typedef svn_error_t * (*svn_io_walk_func_t) (void *baton, 00667 const char *path, 00668 const apr_finfo_t *finfo, 00669 apr_pool_t *pool); 00670 00671 /** This function will recursively walk over the files and directories 00672 * rooted at @a dirname, a utf8-encoded path. For each file or directory, 00673 * @a walk_func is invoked, passing in the @a walk_baton, the utf8-encoded 00674 * full path to the entry, an @c apr_finfo_t structure, and a temporary 00675 * pool for allocations. For any directory, @a walk_func will be invoked 00676 * on the directory itself before being invoked on any subdirectories or 00677 * files within the directory. 00678 * 00679 * The set of information passed to @a walk_func is specified by @a wanted, 00680 * and the items specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME. 00681 * 00682 * All allocations will be performed in @a pool. 00683 */ 00684 svn_error_t *svn_io_dir_walk (const char *dirname, 00685 apr_int32_t wanted, 00686 svn_io_walk_func_t walk_func, 00687 void *walk_baton, 00688 apr_pool_t *pool); 00689 00690 /** 00691 * Start @a cmd with @a args, using utf8-encoded @a path as working 00692 * directory. Connect @a cmd's stdin, stdout, and stderr to @a infile, 00693 * @a outfile, and @a errfile, except where they are null. Return the 00694 * process handle for the invoked program in @a *cmd_proc. 00695 * 00696 * @a args is a list of utf8-encoded <tt>const char *</tt> arguments, 00697 * terminated by @c NULL. @a args[0] is the name of the program, though it 00698 * need not be the same as @a cmd. 00699 * 00700 * @a inherit sets whether the invoked program shall inherit its environment or 00701 * run "clean". 00702 * 00703 * @since New in 1.3. 00704 */ 00705 svn_error_t *svn_io_start_cmd (apr_proc_t *cmd_proc, 00706 const char *path, 00707 const char *cmd, 00708 const char *const *args, 00709 svn_boolean_t inherit, 00710 apr_file_t *infile, 00711 apr_file_t *outfile, 00712 apr_file_t *errfile, 00713 apr_pool_t *pool); 00714 00715 /** 00716 * Wait for the process @a *cmd_proc to complete and optionally retrieve 00717 * its exit code. @a cmd is used only in error messages. 00718 * 00719 * If @a exitcode is not null, @a *exitcode will contain the exit code 00720 * of the process upon return, and if @a exitwhy is not null, @a 00721 * *exitwhy will indicate why the process terminated. If @a exitwhy is 00722 * null, and the exit reason is not @c APR_PROC_CHECK_EXIT(), or if 00723 * @a exitcode is null and the exit code is non-zero, then an 00724 * @c SVN_ERR_EXTERNAL_PROGRAM error will be returned. 00725 * 00726 * @since New in 1.3. 00727 */ 00728 svn_error_t *svn_io_wait_for_cmd (apr_proc_t *cmd_proc, 00729 const char *cmd, 00730 int *exitcode, 00731 apr_exit_why_e *exitwhy, 00732 apr_pool_t *pool); 00733 00734 /** Run a command to completion, by first calling svn_io_start_cmd() and 00735 * then calling svn_io_wait_for_cmd(). The parameters correspond to 00736 * the the same-named parameters of those two functions. 00737 */ 00738 svn_error_t *svn_io_run_cmd (const char *path, 00739 const char *cmd, 00740 const char *const *args, 00741 int *exitcode, 00742 apr_exit_why_e *exitwhy, 00743 svn_boolean_t inherit, 00744 apr_file_t *infile, 00745 apr_file_t *outfile, 00746 apr_file_t *errfile, 00747 apr_pool_t *pool); 00748 00749 /** Invoke @c the configured diff program, with @a user_args (an array 00750 * of utf8-encoded @a num_user_args arguments), if they are specified, 00751 * or "-u" if they are not. 00752 * 00753 * Diff runs in utf8-encoded @a dir, and its exit status is stored in 00754 * @a exitcode, if it is not @c NULL. 00755 * 00756 * If @a label1 and/or @a label2 are not null they will be passed to the diff 00757 * process as the arguments of "-L" options. @a label1 and @a label2 are also 00758 * in utf8, and will be converted to native charset along with the other args. 00759 * 00760 * @a from is the first file passed to diff, and @a to is the second. The 00761 * stdout of diff will be sent to @a outfile, and the stderr to @a errfile. 00762 * 00763 * @a diff_cmd must be non-null. 00764 * 00765 * Do all allocation in @a pool. 00766 */ 00767 svn_error_t *svn_io_run_diff (const char *dir, 00768 const char *const *user_args, 00769 int num_user_args, 00770 const char *label1, 00771 const char *label2, 00772 const char *from, 00773 const char *to, 00774 int *exitcode, 00775 apr_file_t *outfile, 00776 apr_file_t *errfile, 00777 const char *diff_cmd, 00778 apr_pool_t *pool); 00779 00780 00781 /** Invoke @c the configured diff3 program, in utf8-encoded @a dir 00782 * like this: 00783 * 00784 * diff3 -Em @a mine @a older @a yours > @a merged 00785 * 00786 * (See the diff3 documentation for details.) 00787 * 00788 * @a mine, @a older, and @a yours are utf8-encoded paths, relative to @a dir, 00789 * to three files that already exist. @a merged is an open file handle, and 00790 * is left open after the merge result is written to it. (@a merged 00791 * should *not* be the same file as @a mine, or nondeterministic things 00792 * may happen!) 00793 * 00794 * @a mine_label, @a older_label, @a yours_label are utf8-encoded label 00795 * parameters for diff3's -L option. Any of them may be @c NULL, in 00796 * which case the corresponding @a mine, @a older, or @a yours parameter is 00797 * used instead. 00798 * 00799 * Set @a *exitcode to diff3's exit status. If @a *exitcode is anything 00800 * other than 0 or 1, then return @c SVN_ERR_EXTERNAL_PROGRAM. (Note the 00801 * following from the diff3 info pages: "An exit status of 0 means 00802 * `diff3' was successful, 1 means some conflicts were found, and 2 00803 * means trouble.") 00804 * 00805 * @a diff3_cmd must be non-null. 00806 * 00807 * Do all allocation in @a pool. 00808 */ 00809 svn_error_t *svn_io_run_diff3 (const char *dir, 00810 const char *mine, 00811 const char *older, 00812 const char *yours, 00813 const char *mine_label, 00814 const char *older_label, 00815 const char *yours_label, 00816 apr_file_t *merged, 00817 int *exitcode, 00818 const char *diff3_cmd, 00819 apr_pool_t *pool); 00820 00821 00822 /** Examine utf8-encoded @a file to determine if it can be described by a 00823 * known (as in, known by this function) Multipurpose Internet Mail 00824 * Extension (MIME) type. If so, set @a *mimetype to a character string 00825 * describing the MIME type, else set it to @c NULL. Use @a pool for any 00826 * necessary allocations. 00827 */ 00828 svn_error_t *svn_io_detect_mimetype (const char **mimetype, 00829 const char *file, 00830 apr_pool_t *pool); 00831 00832 00833 /** Wrapper for apr_file_open(), which see. @a fname is utf8-encoded. */ 00834 svn_error_t * 00835 svn_io_file_open (apr_file_t **new_file, const char *fname, 00836 apr_int32_t flag, apr_fileperms_t perm, 00837 apr_pool_t *pool); 00838 00839 00840 /** Wrapper for apr_file_close(), which see. */ 00841 svn_error_t * 00842 svn_io_file_close (apr_file_t *file, apr_pool_t *pool); 00843 00844 00845 /** Wrapper for apr_file_getc(), which see. */ 00846 svn_error_t * 00847 svn_io_file_getc (char *ch, apr_file_t *file, apr_pool_t *pool); 00848 00849 00850 /** Wrapper for apr_file_info_get(), which see. */ 00851 svn_error_t * 00852 svn_io_file_info_get (apr_finfo_t *finfo, apr_int32_t wanted, 00853 apr_file_t *file, apr_pool_t *pool); 00854 00855 00856 /** Wrapper for apr_file_read(), which see. */ 00857 svn_error_t * 00858 svn_io_file_read (apr_file_t *file, void *buf, 00859 apr_size_t *nbytes, apr_pool_t *pool); 00860 00861 00862 /** Wrapper for apr_file_read_full(), which see. */ 00863 svn_error_t * 00864 svn_io_file_read_full (apr_file_t *file, void *buf, 00865 apr_size_t nbytes, apr_size_t *bytes_read, 00866 apr_pool_t *pool); 00867 00868 00869 /** Wrapper for apr_file_seek(), which see. */ 00870 svn_error_t * 00871 svn_io_file_seek (apr_file_t *file, apr_seek_where_t where, 00872 apr_off_t *offset, apr_pool_t *pool); 00873 00874 00875 /** Wrapper for apr_file_write(), which see. */ 00876 svn_error_t * 00877 svn_io_file_write (apr_file_t *file, const void *buf, 00878 apr_size_t *nbytes, apr_pool_t *pool); 00879 00880 00881 /** Wrapper for apr_file_write_full(), which see. */ 00882 svn_error_t * 00883 svn_io_file_write_full (apr_file_t *file, const void *buf, 00884 apr_size_t nbytes, apr_size_t *bytes_written, 00885 apr_pool_t *pool); 00886 00887 00888 /** Wrapper for apr_stat(), which see. @a fname is utf8-encoded. */ 00889 svn_error_t * 00890 svn_io_stat (apr_finfo_t *finfo, const char *fname, 00891 apr_int32_t wanted, apr_pool_t *pool); 00892 00893 00894 /** Wrapper for apr_file_rename(), which see. @a from_path and @a to_path 00895 * are utf8-encoded. 00896 */ 00897 svn_error_t * 00898 svn_io_file_rename (const char *from_path, const char *to_path, 00899 apr_pool_t *pool); 00900 00901 00902 /** Move the file from @a from_path to @a to_path. 00903 * Overwrite @a to_path if it exists. 00904 * 00905 * @since New in 1.3. 00906 */ 00907 svn_error_t * 00908 svn_io_file_move (const char *from_path, const char *to_path, 00909 apr_pool_t *pool); 00910 00911 00912 /** Wrapper for apr_dir_make(), which see. @a path is utf8-encoded. */ 00913 svn_error_t * 00914 svn_io_dir_make (const char *path, apr_fileperms_t perm, apr_pool_t *pool); 00915 00916 /** Same as svn_io_dir_make(), but sets the hidden attribute on the 00917 directory on systems that support it. */ 00918 svn_error_t * 00919 svn_io_dir_make_hidden (const char *path, apr_fileperms_t perm, 00920 apr_pool_t *pool); 00921 00922 /** 00923 * Same as svn_io_dir_make(), but attempts to set the sgid on the 00924 * directory on systems that support it. Does not return an error if 00925 * the attempt to set the sgid bit fails. On Unix filesystems, 00926 * setting the sgid bit on a directory ensures that files and 00927 * subdirectories created within inherit group ownership from the 00928 * parent instead of from the primary gid. 00929 * 00930 * @since New in 1.1. 00931 */ 00932 svn_error_t * 00933 svn_io_dir_make_sgid (const char *path, apr_fileperms_t perm, 00934 apr_pool_t *pool); 00935 00936 /** Wrapper for apr_dir_open(), which see. @a dirname is utf8-encoded. */ 00937 svn_error_t * 00938 svn_io_dir_open (apr_dir_t **new_dir, const char *dirname, apr_pool_t *pool); 00939 00940 00941 /** Wrapper for apr_dir_remove(), which see. @a dirname is utf8-encoded. 00942 * @note This function has this name to avoid confusion with 00943 * svn_io_remove_dir(), which is recursive. 00944 */ 00945 svn_error_t * 00946 svn_io_dir_remove_nonrecursive (const char *dirname, apr_pool_t *pool); 00947 00948 00949 /** Wrapper for apr_dir_read(), which see. Ensures that @a finfo->name is 00950 * utf8-encoded, which means allocating @a finfo->name in @a pool, which may 00951 * or may not be the same as @a finfo's pool. Use @a pool for error allocation 00952 * as well. 00953 */ 00954 svn_error_t * 00955 svn_io_dir_read (apr_finfo_t *finfo, 00956 apr_int32_t wanted, 00957 apr_dir_t *thedir, 00958 apr_pool_t *pool); 00959 00960 00961 00962 /** Version/format files. 00963 * 00964 * @defgroup svn_io_format_files version/format files 00965 * @{ 00966 */ 00967 00968 /** Set @a *version to the integer that starts the file at @a path. If the 00969 * file does not begin with a series of digits followed by a newline, 00970 * return the error @c SVN_ERR_BAD_VERSION_FILE_FORMAT. Use @a pool for 00971 * all allocations. 00972 */ 00973 svn_error_t * 00974 svn_io_read_version_file (int *version, const char *path, apr_pool_t *pool); 00975 00976 /** Create (or overwrite) the file at @a path with new contents, 00977 * formatted as a non-negative integer @a version followed by a single 00978 * newline. On successful completion the file will be read-only. Use 00979 * @a pool for all allocations. 00980 */ 00981 svn_error_t * 00982 svn_io_write_version_file (const char *path, int version, apr_pool_t *pool); 00983 00984 /** @} */ 00985 00986 #ifdef __cplusplus 00987 } 00988 #endif /* __cplusplus */ 00989 00990 #endif /* SVN_IO_H */