Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

svn_io.h

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

Generated on Thu Aug 25 00:11:40 2005 for Subversion by  doxygen 1.3.9.1