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 /** 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 */

Generated on Wed Oct 4 23:59:39 2006 for Subversion by  doxygen 1.4.7