Subversion 1.6.16

svn_io.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2008 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_time.h>
00031 #include <apr_hash.h>
00032 #include <apr_tables.h>
00033 #include <apr_file_io.h>
00034 #include <apr_file_info.h>
00035 #include <apr_thread_proc.h>  /* for apr_proc_t, apr_exit_why_e */
00036 
00037 #include "svn_types.h"
00038 #include "svn_string.h"
00039 #include "svn_checksum.h"
00040 
00041 #ifdef __cplusplus
00042 extern "C" {
00043 #endif /* __cplusplus */
00044 
00045 
00046 
00047 /** Used as an argument when creating temporary files to indicate
00048  * when a file should be removed.
00049  *
00050  * @since New in 1.4.
00051  *
00052  * Not specifying any of these means no removal at all. */
00053 typedef enum svn_io_file_del_t
00054 {
00055   /** No deletion ever */
00056   svn_io_file_del_none = 0,
00057   /** Remove when the file is closed */
00058   svn_io_file_del_on_close,
00059   /** Remove when the associated pool is cleared */
00060   svn_io_file_del_on_pool_cleanup
00061 } svn_io_file_del_t;
00062 
00063 
00064 
00065 /** Represents the kind and special status of a directory entry.
00066  *
00067  * @since New in 1.3.
00068  */
00069 typedef struct svn_io_dirent_t {
00070   /** The kind of this entry. */
00071   svn_node_kind_t kind;
00072   /** If @c kind is @c svn_node_file, whether this entry is a special file;
00073    * else FALSE.
00074    *
00075    * @see svn_io_check_special_path().
00076    */
00077   svn_boolean_t special;
00078 } svn_io_dirent_t;
00079 
00080 /** Determine the @a kind of @a path.  @a path should be UTF-8 encoded.
00081  *
00082  * If @a path is a file, set @a *kind to @c svn_node_file.
00083  *
00084  * If @a path is a directory, set @a *kind to @c svn_node_dir.
00085  *
00086  * If @a path does not exist, set @a *kind to @c svn_node_none.
00087  *
00088  * If @a path exists but is none of the above, set @a *kind to @c
00089  * svn_node_unknown.
00090  *
00091  * If @a path is not a valid pathname, set @a *kind to #svn_node_none.  If
00092  * unable to determine @a path's kind for any other reason, return an error,
00093  * with @a *kind's value undefined.
00094  *
00095  * Use @a pool for temporary allocations.
00096  *
00097  * @see svn_node_kind_t
00098  */
00099 svn_error_t *
00100 svn_io_check_path(const char *path,
00101                   svn_node_kind_t *kind,
00102                   apr_pool_t *pool);
00103 
00104 /**
00105  * Like svn_io_check_path(), but also set *is_special to @c TRUE if
00106  * the path is not a normal file.
00107  *
00108  * @since New in 1.1.
00109  */
00110 svn_error_t *
00111 svn_io_check_special_path(const char *path,
00112                           svn_node_kind_t *kind,
00113                           svn_boolean_t *is_special,
00114                           apr_pool_t *pool);
00115 
00116 /** Like svn_io_check_path(), but resolve symlinks.  This returns the
00117     same varieties of @a kind as svn_io_check_path(). */
00118 svn_error_t *
00119 svn_io_check_resolved_path(const char *path,
00120                            svn_node_kind_t *kind,
00121                            apr_pool_t *pool);
00122 
00123 
00124 /** Open a new file (for reading and writing) with a unique name based on
00125  * utf-8 encoded @a filename, in the directory @a dirpath.  The file handle is
00126  * returned in @a *file, and the name, which ends with @a suffix, is returned
00127  * in @a *unique_name, also utf8-encoded.  Either @a file or @a unique_name
00128  * may be @c NULL.
00129  *
00130  * If @a delete_when is @c svn_io_file_del_on_close, then the @c APR_DELONCLOSE
00131  * flag will be used when opening the file.  The @c APR_BUFFERED flag will
00132  * always be used.
00133  *
00134  * The first attempt will just append @a suffix.  If the result is not
00135  * a unique name, then subsequent attempts will append a dot,
00136  * followed by an iteration number ("2", then "3", and so on),
00137  * followed by the suffix.  For example, successive calls to
00138  *
00139  *    svn_io_open_uniquely_named(&f, &u, "tests/t1/A/D/G", "pi", ".tmp", ...)
00140  *
00141  * will open
00142  *
00143  *    tests/t1/A/D/G/pi.tmp
00144  *    tests/t1/A/D/G/pi.2.tmp
00145  *    tests/t1/A/D/G/pi.3.tmp
00146  *    tests/t1/A/D/G/pi.4.tmp
00147  *    tests/t1/A/D/G/pi.5.tmp
00148  *    ...
00149  *
00150  * Assuming @a suffix is non-empty, @a *unique_name will never be exactly
00151  * the same as @a filename, even if @a filename does not exist.
00152  *
00153  * If @a dirpath is NULL, then the directory returned by svn_io_temp_dir()
00154  * will be used.
00155  *
00156  * If @a filename is NULL, then "tempfile" will be used.
00157  *
00158  * If @a suffix is NULL, then ".tmp" will be used.
00159  *
00160  * Allocates @a *file and @a *unique_name in @a result_pool. All
00161  * intermediate allocations will be performed in @a scratch_pool.
00162  *
00163  * If no unique name can be found, @c SVN_ERR_IO_UNIQUE_NAMES_EXHAUSTED is
00164  * the error returned.
00165  *
00166  * Claim of Historical Inevitability: this function was written
00167  * because
00168  *
00169  *    - tmpnam() is not thread-safe.
00170  *    - tempname() tries standard system tmp areas first.
00171  *
00172  * @since New in 1.6
00173  */
00174 svn_error_t *
00175 svn_io_open_uniquely_named(apr_file_t **file,
00176                            const char **unique_name,
00177                            const char *dirpath,
00178                            const char *filename,
00179                            const char *suffix,
00180                            svn_io_file_del_t delete_when,
00181                            apr_pool_t *result_pool,
00182                            apr_pool_t *scratch_pool);
00183 
00184 
00185 /** Create a writable file in the directory @a dirpath. The file will have
00186  * an arbitrary and unique name, and the full path will be returned in
00187  * @a temp_path. The file will be returned in @a file. Both will be
00188  * allocated from @a result_pool.
00189  *
00190  * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
00191  * (Note that when using the system-provided temp directory, it may not
00192  * be possibly to atomically rename the resulting file due to cross-device
00193  * issues.)
00194  *
00195  * The file will be deleted according to @a delete_when.
00196  *
00197  * Temporary allocations will be performed in @a scratch_pool.
00198  *
00199  * @since New in 1.6
00200  * @see svn_stream_open_unique()
00201  */
00202 svn_error_t *
00203 svn_io_open_unique_file3(apr_file_t **file,
00204                          const char **temp_path,
00205                          const char *dirpath,
00206                          svn_io_file_del_t delete_when,
00207                          apr_pool_t *result_pool,
00208                          apr_pool_t *scratch_pool);
00209 
00210 
00211 /** Like svn_io_open_uniquely_named(), but takes a joined dirpath and
00212  * filename, and a single pool.
00213  *
00214  * @since New in 1.4
00215  *
00216  * @deprecated Provided for backward compatibility with the 1.5 API
00217  */
00218 SVN_DEPRECATED
00219 svn_error_t *
00220 svn_io_open_unique_file2(apr_file_t **f,
00221                          const char **unique_name_p,
00222                          const char *path,
00223                          const char *suffix,
00224                          svn_io_file_del_t delete_when,
00225                          apr_pool_t *pool);
00226 
00227 /** Like svn_io_open_unique_file2, but can't delete on pool cleanup.
00228  *
00229  * @deprecated Provided for backward compatibility with the 1.0 API
00230  *
00231  * @note In 1.4 the API was extended to require either @a f or
00232  *       @a unique_name_p (the other can be NULL).  Before that, both were
00233  *       required.
00234  */
00235 SVN_DEPRECATED
00236 svn_error_t *
00237 svn_io_open_unique_file(apr_file_t **f,
00238                         const char **unique_name_p,
00239                         const char *path,
00240                         const char *suffix,
00241                         svn_boolean_t delete_on_close,
00242                         apr_pool_t *pool);
00243 
00244 
00245 /**
00246  * Like svn_io_open_unique_file(), except that instead of creating a
00247  * file, a symlink is generated that references the path @a dest.
00248  *
00249  * @since New in 1.1.
00250  */
00251 svn_error_t *
00252 svn_io_create_unique_link(const char **unique_name_p,
00253                           const char *path,
00254                           const char *dest,
00255                           const char *suffix,
00256                           apr_pool_t *pool);
00257 
00258 
00259 /**
00260  * Set @a *dest to the path that the symlink at @a path references.
00261  * Allocate the string from @a pool.
00262  *
00263  * @since New in 1.1.
00264  */
00265 svn_error_t *
00266 svn_io_read_link(svn_string_t **dest,
00267                  const char *path,
00268                  apr_pool_t *pool);
00269 
00270 
00271 /** Set @a *dir to a directory path (allocated in @a pool) deemed
00272  * usable for the creation of temporary files and subdirectories.
00273  */
00274 svn_error_t *
00275 svn_io_temp_dir(const char **dir,
00276                 apr_pool_t *pool);
00277 
00278 
00279 /** Copy @a src to @a dst atomically, in a "byte-for-byte" manner.
00280  * Overwrite @a dst if it exists, else create it.  Both @a src and @a dst
00281  * are utf8-encoded filenames.  If @a copy_perms is TRUE, set @a dst's
00282  * permissions to match those of @a src.
00283  */
00284 svn_error_t *
00285 svn_io_copy_file(const char *src,
00286                  const char *dst,
00287                  svn_boolean_t copy_perms,
00288                  apr_pool_t *pool);
00289 
00290 
00291 /** Copy permission flags from @a src onto the file at @a dst. Both
00292  * filenames are utf8-encoded filenames.
00293  */
00294 svn_error_t *
00295 svn_io_copy_perms(const char *src,
00296                   const char *dst,
00297                   apr_pool_t *pool);
00298 
00299 
00300 /**
00301  * Copy symbolic link @a src to @a dst atomically.  Overwrite @a dst
00302  * if it exists, else create it.  Both @a src and @a dst are
00303  * utf8-encoded filenames.  After copying, the @a dst link will point
00304  * to the same thing @a src does.
00305  *
00306  * @since New in 1.1.
00307  */
00308 svn_error_t *
00309 svn_io_copy_link(const char *src,
00310                  const char *dst,
00311                  apr_pool_t *pool);
00312 
00313 
00314 /** Recursively copy directory @a src into @a dst_parent, as a new entry named
00315  * @a dst_basename.  If @a dst_basename already exists in @a dst_parent,
00316  * return error.  @a copy_perms will be passed through to svn_io_copy_file()
00317  * when any files are copied.  @a src, @a dst_parent, and @a dst_basename are
00318  * all utf8-encoded.
00319  *
00320  * If @a cancel_func is non-NULL, invoke it with @a cancel_baton at
00321  * various points during the operation.  If it returns any error
00322  * (typically @c SVN_ERR_CANCELLED), return that error immediately.
00323  */
00324 svn_error_t *
00325 svn_io_copy_dir_recursively(const char *src,
00326                             const char *dst_parent,
00327                             const char *dst_basename,
00328                             svn_boolean_t copy_perms,
00329                             svn_cancel_func_t cancel_func,
00330                             void *cancel_baton,
00331                             apr_pool_t *pool);
00332 
00333 
00334 /** Create directory @a path on the file system, creating intermediate
00335  * directories as required, like <tt>mkdir -p</tt>.  Report no error if @a
00336  * path already exists.  @a path is utf8-encoded.
00337  *
00338  * This is essentially a wrapper for apr_dir_make_recursive(), passing
00339  * @c APR_OS_DEFAULT as the permissions.
00340  */
00341 svn_error_t *
00342 svn_io_make_dir_recursively(const char *path,
00343                             apr_pool_t *pool);
00344 
00345 
00346 /** Set @a *is_empty_p to @c TRUE if directory @a path is empty, else to
00347  * @c FALSE if it is not empty.  @a path must be a directory, and is
00348  * utf8-encoded.  Use @a pool for temporary allocation.
00349  */
00350 svn_error_t *
00351 svn_io_dir_empty(svn_boolean_t *is_empty_p,
00352                  const char *path,
00353                  apr_pool_t *pool);
00354 
00355 
00356 /** Append @a src to @a dst.  @a dst will be appended to if it exists, else it
00357  * will be created.  Both @a src and @a dst are utf8-encoded.
00358  */
00359 svn_error_t *
00360 svn_io_append_file(const char *src,
00361                    const char *dst,
00362                    apr_pool_t *pool);
00363 
00364 
00365 /** Make a file as read-only as the operating system allows.
00366  * @a path is the utf8-encoded path to the file. If @a ignore_enoent is
00367  * @c TRUE, don't fail if the target file doesn't exist.
00368  *
00369  * If @a path is a symlink, do nothing.
00370  *
00371  * @note If @a path is a directory, act on it as though it were a
00372  * file, as described above, but note that you probably don't want to
00373  * call this function on directories.  We have left it effective on
00374  * directories for compatibility reasons, but as its name implies, it
00375  * should be used only for files.
00376  */
00377 svn_error_t *
00378 svn_io_set_file_read_only(const char *path,
00379                           svn_boolean_t ignore_enoent,
00380                           apr_pool_t *pool);
00381 
00382 
00383 /** Make a file as writable as the operating system allows.
00384  * @a path is the utf8-encoded path to the file.  If @a ignore_enoent is
00385  * @c TRUE, don't fail if the target file doesn't exist.
00386  * @warning On Unix this function will do the equivalent of chmod a+w path.
00387  * If this is not what you want you should not use this function, but rather
00388  * use apr_file_perms_set().
00389  *
00390  * If @a path is a symlink, do nothing.
00391  *
00392  * @note If @a path is a directory, act on it as though it were a
00393  * file, as described above, but note that you probably don't want to
00394  * call this function on directories.  We have left it effective on
00395  * directories for compatibility reasons, but as its name implies, it
00396  * should be used only for files.
00397  */
00398 svn_error_t *
00399 svn_io_set_file_read_write(const char *path,
00400                            svn_boolean_t ignore_enoent,
00401                            apr_pool_t *pool);
00402 
00403 
00404 /** Similar to svn_io_set_file_read_* functions.
00405  * Change the read-write permissions of a file.
00406  * @since New in 1.1.
00407  *
00408  * When making @a path read-write on operating systems with unix style
00409  * permissions, set the permissions on @a path to the permissions that
00410  * are set when a new file is created (effectively honoring the user's
00411  * umask).
00412  *
00413  * When making the file read-only on operating systems with unix style
00414  * permissions, remove all write permissions.
00415  *
00416  * On other operating systems, toggle the file's "writability" as much as
00417  * the operating system allows.
00418  *
00419  * @a path is the utf8-encoded path to the file.  If @a enable_write
00420  * is @c TRUE, then make the file read-write.  If @c FALSE, make it
00421  * read-only.  If @a ignore_enoent is @c TRUE, don't fail if the target
00422  * file doesn't exist.
00423  *
00424  * @deprecated Provided for backward compatibility with the 1.3 API.
00425  */
00426 SVN_DEPRECATED
00427 svn_error_t *
00428 svn_io_set_file_read_write_carefully(const char *path,
00429                                      svn_boolean_t enable_write,
00430                                      svn_boolean_t ignore_enoent,
00431                                      apr_pool_t *pool);
00432 
00433 /** Set @a path's "executability" (but do nothing if it is a symlink).
00434  *
00435  * @a path is the utf8-encoded path to the file.  If @a executable
00436  * is @c TRUE, then make the file executable.  If @c FALSE, make it
00437  * non-executable.  If @a ignore_enoent is @c TRUE, don't fail if the target
00438  * file doesn't exist.
00439  *
00440  * When making the file executable on operating systems with unix style
00441  * permissions, never add an execute permission where there is not
00442  * already a read permission: that is, only make the file executable
00443  * for the user, group or world if the corresponding read permission
00444  * is already set for user, group or world.
00445  *
00446  * When making the file non-executable on operating systems with unix style
00447  * permissions, remove all execute permissions.
00448  *
00449  * On other operating systems, toggle the file's "executability" as much as
00450  * the operating system allows.
00451  *
00452  * @note If @a path is a directory, act on it as though it were a
00453  * file, as described above, but note that you probably don't want to
00454  * call this function on directories.  We have left it effective on
00455  * directories for compatibility reasons, but as its name implies, it
00456  * should be used only for files.
00457  */
00458 svn_error_t *
00459 svn_io_set_file_executable(const char *path,
00460                            svn_boolean_t executable,
00461                            svn_boolean_t ignore_enoent,
00462                            apr_pool_t *pool);
00463 
00464 /** Determine whether a file is executable by the current user.
00465  * Set @a *executable to @c TRUE if the file @a path is executable by the
00466  * current user, otherwise set it to @c FALSE.
00467  *
00468  * On Windows and on platforms without userids, always returns @c FALSE.
00469  */
00470 svn_error_t *
00471 svn_io_is_file_executable(svn_boolean_t *executable,
00472                           const char *path,
00473                           apr_pool_t *pool);
00474 
00475 
00476 /** Read a line from @a file into @a buf, but not exceeding @a *limit bytes.
00477  * Does not include newline, instead '\\0' is put there.
00478  * Length (as in strlen) is returned in @a *limit.
00479  * @a buf should be pre-allocated.
00480  * @a file should be already opened.
00481  *
00482  * When the file is out of lines, @c APR_EOF will be returned.
00483  */
00484 svn_error_t *
00485 svn_io_read_length_line(apr_file_t *file,
00486                         char *buf,
00487                         apr_size_t *limit,
00488                         apr_pool_t *pool);
00489 
00490 
00491 /** Set @a *apr_time to the time of last modification of the contents of the
00492  * file @a path.  @a path is utf8-encoded.
00493  *
00494  * @note This is the APR mtime which corresponds to the traditional mtime
00495  * on Unix, and the last write time on Windows.
00496  */
00497 svn_error_t *
00498 svn_io_file_affected_time(apr_time_t *apr_time,
00499                           const char *path,
00500                           apr_pool_t *pool);
00501 
00502 /** Set the timestamp of file @a path to @a apr_time.  @a path is
00503  *  utf8-encoded.
00504  *
00505  * @note This is the APR mtime which corresponds to the traditional mtime
00506  * on Unix, and the last write time on Windows.
00507  */
00508 svn_error_t *
00509 svn_io_set_file_affected_time(apr_time_t apr_time,
00510                               const char *path,
00511                               apr_pool_t *pool);
00512 
00513 /** Sleep to ensure that any files modified after we exit have a different
00514  * timestamp than the one we recorded. If @a path is not NULL, check if we
00515  * can determine how long we should wait for a new timestamp on the filesystem
00516  * containing @a path, an existing file or directory. If @a path is NULL or we
00517  * can't determine the timestamp resolution, sleep until the next second.
00518  *
00519  * Use @a pool for any necessary allocations. @a pool can be null if @a path
00520  * is NULL.
00521  *
00522  * Errors while retrieving the timestamp resolution will result in sleeping
00523  * to the next second, to keep the working copy stable in error conditions.
00524  *
00525  * @since New in 1.6.
00526  */
00527 void
00528 svn_io_sleep_for_timestamps(const char *path, apr_pool_t *pool);
00529 
00530 /** Set @a *different_p to non-zero if @a file1 and @a file2 have different
00531  * sizes, else set to zero.  Both @a file1 and @a file2 are utf8-encoded.
00532  *
00533  * Setting @a *different_p to zero does not mean the files definitely
00534  * have the same size, it merely means that the sizes are not
00535  * definitely different.  That is, if the size of one or both files
00536  * cannot be determined, then the sizes are not known to be different,
00537  * so @a *different_p is set to 0.
00538  */
00539 svn_error_t *
00540 svn_io_filesizes_different_p(svn_boolean_t *different_p,
00541                              const char *file1,
00542                              const char *file2,
00543                              apr_pool_t *pool);
00544 
00545 
00546 /** Return in @a *checksum the checksum of type @a kind of @a file
00547  * Use @a pool for temporary allocations and to allocate @a *checksum.
00548  *
00549  * @since New in 1.6.
00550  */
00551 svn_error_t *
00552 svn_io_file_checksum2(svn_checksum_t **checksum,
00553                       const char *file,
00554                       svn_checksum_kind_t kind,
00555                       apr_pool_t *pool);
00556 
00557 
00558 /** Put the md5 checksum of @a file into @a digest.
00559  * @a digest points to @c APR_MD5_DIGESTSIZE bytes of storage.
00560  * Use @a pool only for temporary allocations.
00561  *
00562  * @deprecated Provided for backward compatibility with the 1.5 API.
00563  */
00564 SVN_DEPRECATED
00565 svn_error_t *
00566 svn_io_file_checksum(unsigned char digest[],
00567                      const char *file,
00568                      apr_pool_t *pool);
00569 
00570 
00571 /** Set @a *same to TRUE if @a file1 and @a file2 have the same
00572  * contents, else set it to FALSE.  Use @a pool for temporary allocations.
00573  */
00574 svn_error_t *
00575 svn_io_files_contents_same_p(svn_boolean_t *same,
00576                              const char *file1,
00577                              const char *file2,
00578                              apr_pool_t *pool);
00579 
00580 /** Create file at utf8-encoded @a file with contents @a contents.
00581  * @a file must not already exist.
00582  * Use @a pool for memory allocations.
00583  */
00584 svn_error_t *
00585 svn_io_file_create(const char *file,
00586                    const char *contents,
00587                    apr_pool_t *pool);
00588 
00589 /**
00590  * Lock file at @a lock_file. If @a exclusive is TRUE,
00591  * obtain exclusive lock, otherwise obtain shared lock.
00592  * Lock will be automatically released when @a pool is cleared or destroyed.
00593  * Use @a pool for memory allocations.
00594  *
00595  * @deprecated Provided for backward compatibility with the 1.0 API.
00596  */
00597 SVN_DEPRECATED
00598 svn_error_t *
00599 svn_io_file_lock(const char *lock_file,
00600                  svn_boolean_t exclusive,
00601                  apr_pool_t *pool);
00602 
00603 /**
00604  * Lock file at @a lock_file. If @a exclusive is TRUE,
00605  * obtain exclusive lock, otherwise obtain shared lock.
00606  *
00607  * If @a nonblocking is TRUE, do not wait for the lock if it
00608  * is not available: throw an error instead.
00609  *
00610  * Lock will be automatically released when @a pool is cleared or destroyed.
00611  * Use @a pool for memory allocations.
00612  *
00613  * @since New in 1.1.
00614  */
00615 svn_error_t *
00616 svn_io_file_lock2(const char *lock_file,
00617                   svn_boolean_t exclusive,
00618                   svn_boolean_t nonblocking,
00619                   apr_pool_t *pool);
00620 /**
00621  * Flush any unwritten data from @a file to disk.  Use @a pool for
00622  * memory allocations.
00623  *
00624  * @since New in 1.1.
00625  */
00626 svn_error_t *
00627 svn_io_file_flush_to_disk(apr_file_t *file,
00628                           apr_pool_t *pool);
00629 
00630 /** Copy file @a file from location @a src_path to location @a dest_path.
00631  * Use @a pool for memory allocations.
00632  */
00633 svn_error_t *
00634 svn_io_dir_file_copy(const char *src_path,
00635                      const char *dest_path,
00636                      const char *file,
00637                      apr_pool_t *pool);
00638 
00639 
00640 /** Generic byte-streams
00641  *
00642  * @defgroup svn_io_byte_streams Generic byte streams
00643  * @{
00644  */
00645 
00646 /** An abstract stream of bytes--either incoming or outgoing or both.
00647  *
00648  * The creator of a stream sets functions to handle read and write.
00649  * Both of these handlers accept a baton whose value is determined at
00650  * stream creation time; this baton can point to a structure
00651  * containing data associated with the stream.  If a caller attempts
00652  * to invoke a handler which has not been set, it will generate a
00653  * runtime assertion failure.  The creator can also set a handler for
00654  * close requests so that it can flush buffered data or whatever;
00655  * if a close handler is not specified, a close request on the stream
00656  * will simply be ignored.  Note that svn_stream_close() does not
00657  * deallocate the memory used to allocate the stream structure; free
00658  * the pool you created the stream in to free that memory.
00659  *
00660  * The read and write handlers accept length arguments via pointer.
00661  * On entry to the handler, the pointed-to value should be the amount
00662  * of data which can be read or the amount of data to write.  When the
00663  * handler returns, the value is reset to the amount of data actually
00664  * read or written.  Handlers are obliged to complete a read or write
00665  * to the maximum extent possible; thus, a short read with no
00666  * associated error implies the end of the input stream, and a short
00667  * write should never occur without an associated error.
00668  */
00669 typedef struct svn_stream_t svn_stream_t;
00670 
00671 
00672 
00673 /** Read handler function for a generic stream.  @see svn_stream_t. */
00674 typedef svn_error_t *(*svn_read_fn_t)(void *baton,
00675                                       char *buffer,
00676                                       apr_size_t *len);
00677 
00678 /** Write handler function for a generic stream.  @see svn_stream_t. */
00679 typedef svn_error_t *(*svn_write_fn_t)(void *baton,
00680                                        const char *data,
00681                                        apr_size_t *len);
00682 
00683 /** Close handler function for a generic stream.  @see svn_stream_t. */
00684 typedef svn_error_t *(*svn_close_fn_t)(void *baton);
00685 
00686 
00687 /** Create a generic stream.  @see svn_stream_t. */
00688 svn_stream_t *
00689 svn_stream_create(void *baton,
00690                   apr_pool_t *pool);
00691 
00692 /** Set @a stream's baton to @a baton */
00693 void
00694 svn_stream_set_baton(svn_stream_t *stream,
00695                      void *baton);
00696 
00697 /** Set @a stream's read function to @a read_fn */
00698 void
00699 svn_stream_set_read(svn_stream_t *stream,
00700                     svn_read_fn_t read_fn);
00701 
00702 /** Set @a stream's write function to @a write_fn */
00703 void
00704 svn_stream_set_write(svn_stream_t *stream,
00705                      svn_write_fn_t write_fn);
00706 
00707 /** Set @a stream's close function to @a close_fn */
00708 void
00709 svn_stream_set_close(svn_stream_t *stream,
00710                      svn_close_fn_t close_fn);
00711 
00712 
00713 /** Create a stream that is empty for reading and infinite for writing. */
00714 svn_stream_t *
00715 svn_stream_empty(apr_pool_t *pool);
00716 
00717 /** Return a stream allocated in @a pool which forwards all requests
00718  * to @a stream.  Destruction is explicitly excluded from forwarding.
00719  *
00720  * @see notes/destruction-of-stacked-resources
00721  *
00722  * @since New in 1.4.
00723  */
00724 svn_stream_t *
00725 svn_stream_disown(svn_stream_t *stream,
00726                   apr_pool_t *pool);
00727 
00728 
00729 /** Create a stream to read the file at @a path. It will be opened using
00730  * the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the perms.
00731  * If you'd like to use different values, then open the file yourself, and
00732  * use the svn_stream_from_aprfile2() interface.
00733  *
00734  * The stream will be returned in @a stream, and allocated from @a result_pool.
00735  * Temporary allocations will be performed in @a scratch_pool.
00736  *
00737  * @since New in 1.6
00738  */
00739 svn_error_t *
00740 svn_stream_open_readonly(svn_stream_t **stream,
00741                          const char *path,
00742                          apr_pool_t *result_pool,
00743                          apr_pool_t *scratch_pool);
00744 
00745 
00746 /** Create a stream to write a file at @a path. The file will be *created*
00747  * using the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the
00748  * perms. The file will be created "exclusively", so if it already exists,
00749  * then an error will be thrown. If you'd like to use different values, or
00750  * open an existing file, then open the file yourself, and use the
00751  * svn_stream_from_aprfile2() interface.
00752  *
00753  * The stream will be returned in @a stream, and allocated from @a result_pool.
00754  * Temporary allocations will be performed in @a scratch_pool.
00755  *
00756  * @since New in 1.6
00757  */
00758 svn_error_t *
00759 svn_stream_open_writable(svn_stream_t **stream,
00760                          const char *path,
00761                          apr_pool_t *result_pool,
00762                          apr_pool_t *scratch_pool);
00763 
00764 
00765 /** Create a writable stream to a file in the directory @a dirpath.
00766  * The file will have an arbitrary and unique name, and the full path
00767  * will be returned in @a temp_path. The stream will be returned in
00768  * @a stream. Both will be allocated from @a result_pool.
00769  *
00770  * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
00771  * (Note that when using the system-provided temp directory, it may not
00772  * be possibly to atomically rename the resulting file due to cross-device
00773  * issues.)
00774  *
00775  * The file will be deleted according to @a delete_when.
00776  *
00777  * Temporary allocations will be performed in @a scratch_pool.
00778  *
00779  * @since New in 1.6
00780  * @see svn_io_open_unique_file3()
00781  */
00782 svn_error_t *
00783 svn_stream_open_unique(svn_stream_t **stream,
00784                        const char **temp_path,
00785                        const char *dirpath,
00786                        svn_io_file_del_t delete_when,
00787                        apr_pool_t *result_pool,
00788                        apr_pool_t *scratch_pool);
00789 
00790 
00791 /** Create a stream from an APR file.  For convenience, if @a file is
00792  * @c NULL, an empty stream created by svn_stream_empty() is returned.
00793  *
00794  * This function should normally be called with @a disown set to FALSE,
00795  * in which case closing the stream will also close the underlying file.
00796  *
00797  * If @a disown is TRUE, the stream will disown the underlying file,
00798  * meaning that svn_stream_close() will not close the file.
00799  *
00800  * @since New in 1.4.
00801  */
00802 svn_stream_t *
00803 svn_stream_from_aprfile2(apr_file_t *file,
00804                          svn_boolean_t disown,
00805                          apr_pool_t *pool);
00806 
00807 /** Similar to svn_stream_from_aprfile2(), except that the file will
00808  * always be disowned.
00809  *
00810  * @note The stream returned is not considered to "own" the underlying
00811  *       file, meaning that svn_stream_close() on the stream will not
00812  *       close the file.
00813  *
00814  * @deprecated Provided for backward compatibility with the 1.3 API.
00815  */
00816 SVN_DEPRECATED
00817 svn_stream_t *
00818 svn_stream_from_aprfile(apr_file_t *file,
00819                         apr_pool_t *pool);
00820 
00821 /** Set @a *out to a generic stream connected to stdout, allocated in
00822  * @a pool.  The stream and its underlying APR handle will be closed
00823  * when @a pool is cleared or destroyed.
00824  */
00825 svn_error_t *
00826 svn_stream_for_stdout(svn_stream_t **out,
00827                       apr_pool_t *pool);
00828 
00829 /** Return a generic stream connected to stringbuf @a str.  Allocate the
00830  * stream in @a pool.
00831  */
00832 svn_stream_t *
00833 svn_stream_from_stringbuf(svn_stringbuf_t *str,
00834                           apr_pool_t *pool);
00835 
00836 /** Return a generic read-only stream connected to string @a str.
00837  *  Allocate the stream in @a pool.
00838  */
00839 svn_stream_t *
00840 svn_stream_from_string(const svn_string_t *str,
00841                        apr_pool_t *pool);
00842 
00843 /** Return a stream that decompresses all data read and compresses all
00844  * data written. The stream @a stream is used to read and write all
00845  * compressed data. All compression data structures are allocated on
00846  * @a pool. If compression support is not compiled in then
00847  * svn_stream_compressed() returns @a stream unmodified. Make sure you
00848  * call svn_stream_close() on the stream returned by this function,
00849  * so that all data are flushed and cleaned up.
00850  *
00851  * @note From 1.4, compression support is always compiled in.
00852  */
00853 svn_stream_t *
00854 svn_stream_compressed(svn_stream_t *stream,
00855                       apr_pool_t *pool);
00856 
00857 /** Return a stream that calculates checksums for all data read
00858  * and written.  The stream @a stream is used to read and write all data.
00859  * The stream and the resulting digests are allocated in @a pool.
00860  *
00861  * When the stream is closed, @a *read_checksum and @a *write_checksum
00862  * are set to point to the resulting checksums, of type @a read_checksum_kind
00863  * and @a write_checksum_kind, respectively.
00864  *
00865  * Both @a read_checksum and @a write_checksum can be @c NULL, in which case
00866  * the respective checksum isn't calculated.
00867  *
00868  * If @a read_all is TRUE, make sure that all data available on @a
00869  * stream is read (and checksummed) when the stream is closed.
00870  *
00871  * Read and write operations can be mixed without interfering.
00872  *
00873  * The @a stream passed into this function is closed when the created
00874  * stream is closed.
00875  *
00876  * @since New in 1.6.
00877  */
00878 svn_stream_t *
00879 svn_stream_checksummed2(svn_stream_t *stream,
00880                         svn_checksum_t **read_checksum,
00881                         svn_checksum_t **write_checksum,
00882                         svn_checksum_kind_t checksum_kind,
00883                         svn_boolean_t read_all,
00884                         apr_pool_t *pool);
00885 
00886 /**
00887  * Similar to svn_stream_checksummed2(), but always returning the MD5
00888  * checksum in @a read_digest and @a write_digest.
00889  *
00890  * @since New in 1.4.
00891  * @deprecated Provided for backward compatibility with the 1.5 API.
00892  */
00893 SVN_DEPRECATED
00894 svn_stream_t *
00895 svn_stream_checksummed(svn_stream_t *stream,
00896                        const unsigned char **read_digest,
00897                        const unsigned char **write_digest,
00898                        svn_boolean_t read_all,
00899                        apr_pool_t *pool);
00900 
00901 /** Read from a generic stream. @see svn_stream_t. */
00902 svn_error_t *
00903 svn_stream_read(svn_stream_t *stream,
00904                 char *buffer,
00905                 apr_size_t *len);
00906 
00907 /** Write to a generic stream. @see svn_stream_t. */
00908 svn_error_t *
00909 svn_stream_write(svn_stream_t *stream,
00910                  const char *data,
00911                  apr_size_t *len);
00912 
00913 /** Close a generic stream. @see svn_stream_t. */
00914 svn_error_t *
00915 svn_stream_close(svn_stream_t *stream);
00916 
00917 
00918 /** Write to @a stream using a printf-style @a fmt specifier, passed through
00919  * apr_psprintf() using memory from @a pool.
00920  */
00921 svn_error_t *
00922 svn_stream_printf(svn_stream_t *stream,
00923                   apr_pool_t *pool,
00924                   const char *fmt,
00925                   ...)
00926        __attribute__((format(printf, 3, 4)));
00927 
00928 /** Write to @a stream using a printf-style @a fmt specifier, passed through
00929  * apr_psprintf() using memory from @a pool.  The resulting string
00930  * will be translated to @a encoding before it is sent to @a stream.
00931  *
00932  * @note Use @c APR_LOCALE_CHARSET to translate to the encoding of the
00933  * current locale.
00934  *
00935  * @since New in 1.3.
00936  */
00937 svn_error_t *
00938 svn_stream_printf_from_utf8(svn_stream_t *stream,
00939                             const char *encoding,
00940                             apr_pool_t *pool,
00941                             const char *fmt,
00942                             ...)
00943        __attribute__((format(printf, 4, 5)));
00944 
00945 /** Allocate @a *stringbuf in @a pool, and read into it one line (terminated
00946  * by @a eol) from @a stream. The line-terminator is read from the stream,
00947  * but is not added to the end of the stringbuf.  Instead, the stringbuf
00948  * ends with a usual '\\0'.
00949  *
00950  * If @a stream runs out of bytes before encountering a line-terminator,
00951  * then set @a *eof to @c TRUE, otherwise set @a *eof to FALSE.
00952  */
00953 svn_error_t *
00954 svn_stream_readline(svn_stream_t *stream,
00955                     svn_stringbuf_t **stringbuf,
00956                     const char *eol,
00957                     svn_boolean_t *eof,
00958                     apr_pool_t *pool);
00959 
00960 
00961 /**
00962  * Read the contents of the readable stream @a from and write them to the
00963  * writable stream @a to calling @a cancel_func before copying each chunk.
00964  *
00965  * @a cancel_func may be @c NULL.
00966  *
00967  * @note both @a from and @a to will be closed upon successful completion of
00968  * the copy (but an error may still be returned, based on trying to close
00969  * the two streams). If the closure is not desired, then you can use
00970  * svn_stream_disown() to protect either or both of the streams from
00971  * being closed.
00972  * ### TODO: should close the streams ALWAYS, even on error exit
00973  *
00974  * @since New in 1.6.
00975  */
00976 svn_error_t *
00977 svn_stream_copy3(svn_stream_t *from,
00978                  svn_stream_t *to,
00979                  svn_cancel_func_t cancel_func,
00980                  void *cancel_baton,
00981                  apr_pool_t *pool);
00982 
00983 /**
00984  * Same as svn_stream_copy3() but the streams are not closed.
00985  *
00986  * @since New in 1.5.
00987  * @deprecated Provided for backward compatibility with the 1.5 API.
00988  */
00989 SVN_DEPRECATED
00990 svn_error_t *
00991 svn_stream_copy2(svn_stream_t *from,
00992                  svn_stream_t *to,
00993                  svn_cancel_func_t cancel_func,
00994                  void *cancel_baton,
00995                  apr_pool_t *pool);
00996 
00997 /**
00998  * Same as svn_stream_copy3(), but without the cancellation function
00999  * or stream closing.
01000  *
01001  * @since New in 1.1.
01002  * @deprecated Provided for backward compatibility with the 1.4 API.
01003  */
01004 SVN_DEPRECATED
01005 svn_error_t *
01006 svn_stream_copy(svn_stream_t *from,
01007                 svn_stream_t *to,
01008                 apr_pool_t *pool);
01009 
01010 
01011 /** Set @a *same to TRUE if @a stream1 and @a stream2 have the same
01012  * contents, else set it to FALSE.  Use @a pool for temporary allocations.
01013  *
01014  * @since New in 1.4.
01015  */
01016 svn_error_t *
01017 svn_stream_contents_same(svn_boolean_t *same,
01018                          svn_stream_t *stream1,
01019                          svn_stream_t *stream2,
01020                          apr_pool_t *pool);
01021 
01022 
01023 /** Read the contents of @a stream into memory, returning the data in
01024  * @a result. The stream will be closed when it has been successfully and
01025  * completely read.
01026  *
01027  * The returned memory is allocated in @a result_pool, and any temporary
01028  * allocations are performed in @a scratch_pool.
01029  *
01030  * @note due to memory pseudo-reallocation behavior (due to pools), this
01031  *   can be a memory-intensive operation for large files.
01032  *
01033  * @since New in 1.6
01034  */
01035 svn_error_t *
01036 svn_string_from_stream(svn_string_t **result,
01037                        svn_stream_t *stream,
01038                        apr_pool_t *result_pool,
01039                        apr_pool_t *scratch_pool);
01040 
01041 
01042 /** @} */
01043 
01044 /** Set @a *result to a string containing the contents of @a
01045  * filename, which is either "-" (indicating that stdin should be
01046  * read) or the utf8-encoded path of a real file.
01047  *
01048  * @warning Callers should be aware of possible unexpected results
01049  * when using this function to read from stdin where additional
01050  * stdin-reading processes abound.  For example, if a program tries
01051  * both to invoke an external editor and to read from stdin, stdin
01052  * could be trashed and the editor might act funky or die outright.
01053  *
01054  * @note due to memory pseudo-reallocation behavior (due to pools), this
01055  *   can be a memory-intensive operation for large files.
01056  *
01057  * @since New in 1.5.
01058  */
01059 svn_error_t *
01060 svn_stringbuf_from_file2(svn_stringbuf_t **result,
01061                          const char *filename,
01062                          apr_pool_t *pool);
01063 
01064 /** Similar to svn_stringbuf_from_file2(), except that if @a filename
01065  * is "-", return the error @c SVN_ERR_UNSUPPORTED_FEATURE and don't
01066  * touch @a *result.
01067  *
01068  * @deprecated Provided for backwards compatibility with the 1.4 API.
01069  */
01070 SVN_DEPRECATED
01071 svn_error_t *
01072 svn_stringbuf_from_file(svn_stringbuf_t **result,
01073                         const char *filename,
01074                         apr_pool_t *pool);
01075 
01076 /** Sets @a *result to a string containing the contents of the already opened
01077  * @a file.  Reads from the current position in file to the end.  Does not
01078  * close the file or reset the cursor position.
01079  *
01080  * @note due to memory pseudo-reallocation behavior (due to pools), this
01081  *   can be a memory-intensive operation for large files.
01082  */
01083 svn_error_t *
01084 svn_stringbuf_from_aprfile(svn_stringbuf_t **result,
01085                            apr_file_t *file,
01086                            apr_pool_t *pool);
01087 
01088 /** Remove file @a path, a utf8-encoded path.  This wraps apr_file_remove(),
01089  * converting any error to a Subversion error.
01090  */
01091 svn_error_t *
01092 svn_io_remove_file(const char *path,
01093                    apr_pool_t *pool);
01094 
01095 /** Recursively remove directory @a path.  @a path is utf8-encoded.
01096  * If @a ignore_enoent is @c TRUE, don't fail if the target directory
01097  * doesn't exist.  Use @a pool for temporary allocations.
01098  *
01099  * Because recursive delete of a directory tree can be a lengthy operation,
01100  * provide @a cancel_func and @a cancel_baton for interruptability.
01101  *
01102  * @since New in 1.5.
01103  */
01104 svn_error_t *
01105 svn_io_remove_dir2(const char *path,
01106                    svn_boolean_t ignore_enoent,
01107                    svn_cancel_func_t cancel_func,
01108                    void *cancel_baton,
01109                    apr_pool_t *pool);
01110 
01111 /** Similar to svn_io_remove_dir2(), but with @a ignore_enoent set to
01112  * @c FALSE and @a cancel_func and @a cancel_baton set to @c NULL.
01113  *
01114  * @deprecated Provided for backward compatibility with the 1.4 API
01115  */
01116 SVN_DEPRECATED
01117 svn_error_t *
01118 svn_io_remove_dir(const char *path,
01119                   apr_pool_t *pool);
01120 
01121 /** Read all of the disk entries in directory @a path, a utf8-encoded
01122  * path.  Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
01123  * undefined non-NULL values, allocated in @a pool.
01124  *
01125  * @note The `.' and `..' directories normally returned by
01126  * apr_dir_read() are NOT returned in the hash.
01127  *
01128  * @since New in 1.4.
01129  */
01130 svn_error_t *
01131 svn_io_get_dir_filenames(apr_hash_t **dirents,
01132                          const char *path,
01133                          apr_pool_t *pool);
01134 
01135 /** Read all of the disk entries in directory @a path, a utf8-encoded
01136  * path.  Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
01137  * @c svn_io_dirent_t structures, allocated in @a pool.
01138  *
01139  * @note The `.' and `..' directories normally returned by
01140  * apr_dir_read() are NOT returned in the hash.
01141  *
01142  * @note The kind field in the @a dirents is set according to the mapping
01143  *       as documented for svn_io_check_path()
01144  *
01145  * @since New in 1.3.
01146  */
01147 svn_error_t *
01148 svn_io_get_dirents2(apr_hash_t **dirents,
01149                     const char *path,
01150                     apr_pool_t *pool);
01151 
01152 /** Similar to svn_io_get_dirents2(), but @a *dirents is a hash table
01153  * with @c svn_node_kind_t values.
01154  *
01155  * @deprecated Provided for backwards compatibility with the 1.2 API.
01156  */
01157 SVN_DEPRECATED
01158 svn_error_t *
01159 svn_io_get_dirents(apr_hash_t **dirents,
01160                    const char *path,
01161                    apr_pool_t *pool);
01162 
01163 
01164 /** Callback function type for svn_io_dir_walk() */
01165 typedef svn_error_t * (*svn_io_walk_func_t)(void *baton,
01166                                             const char *path,
01167                                             const apr_finfo_t *finfo,
01168                                             apr_pool_t *pool);
01169 
01170 /** This function will recursively walk over the files and directories
01171  * rooted at @a dirname, a utf8-encoded path. For each file or directory,
01172  * @a walk_func is invoked, passing in the @a walk_baton, the utf8-encoded
01173  * full path to the entry, an @c apr_finfo_t structure, and a temporary
01174  * pool for allocations.  For any directory, @a walk_func will be invoked
01175  * on the directory itself before being invoked on any subdirectories or
01176  * files within the directory.
01177  *
01178  * The set of information passed to @a walk_func is specified by @a wanted,
01179  * and the items specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME.
01180  *
01181  * All allocations will be performed in @a pool.
01182  */
01183 svn_error_t *
01184 svn_io_dir_walk(const char *dirname,
01185                 apr_int32_t wanted,
01186                 svn_io_walk_func_t walk_func,
01187                 void *walk_baton,
01188                 apr_pool_t *pool);
01189 
01190 /**
01191  * Start @a cmd with @a args, using utf8-encoded @a path as working
01192  * directory.  Connect @a cmd's stdin, stdout, and stderr to @a infile,
01193  * @a outfile, and @a errfile, except where they are NULL.  Return the
01194  * process handle for the invoked program in @a *cmd_proc.
01195  *
01196  * @a args is a list of utf8-encoded <tt>const char *</tt> arguments,
01197  * terminated by @c NULL.  @a args[0] is the name of the program, though it
01198  * need not be the same as @a cmd.
01199  *
01200  * If @a inherit is TRUE, the invoked program inherits its environment from
01201  * the caller and @a cmd, if not absolute, is searched for in PATH.
01202  * Otherwise, the invoked program runs with an empty environment and @a cmd
01203  * must be an absolute path.
01204  *
01205  * @note On some platforms, failure to execute @a cmd in the child process
01206  * will result in error output being written to @a errfile, if non-NULL, and
01207  * a non-zero exit status being returned to the parent process.
01208  *
01209  * @since New in 1.3.
01210  */
01211 svn_error_t *
01212 svn_io_start_cmd(apr_proc_t *cmd_proc,
01213                  const char *path,
01214                  const char *cmd,
01215                  const char *const *args,
01216                  svn_boolean_t inherit,
01217                  apr_file_t *infile,
01218                  apr_file_t *outfile,
01219                  apr_file_t *errfile,
01220                  apr_pool_t *pool);
01221 
01222 /**
01223  * Wait for the process @a *cmd_proc to complete and optionally retrieve
01224  * its exit code.  @a cmd is used only in error messages.
01225  *
01226  * If @a exitcode is not NULL, and SVN_NO_ERROR is returned, @a *exitcode
01227  * will contain the exit code of the process.  If @a exitcode is NULL and
01228  * the exit code is non-zero, then an @c SVN_ERR_EXTERNAL_PROGRAM error
01229  * will be returned.
01230  *
01231  * If @a exitwhy is not NULL, and SVN_NO_ERROR is returned, @a *exitwhy
01232  * will indicate why the process terminated.  If @a exitwhy is NULL,
01233  * and the exit reason is not @c APR_PROC_CHECK_EXIT(), then an
01234  * @c SVN_ERR_EXTERNAL_PROGRAM error will be returned.
01235  *
01236  * @since New in 1.3.
01237  */
01238 svn_error_t *
01239 svn_io_wait_for_cmd(apr_proc_t *cmd_proc,
01240                     const char *cmd,
01241                     int *exitcode,
01242                     apr_exit_why_e *exitwhy,
01243                     apr_pool_t *pool);
01244 
01245 /** Run a command to completion, by first calling svn_io_start_cmd() and
01246  * then calling svn_io_wait_for_cmd().  The parameters correspond to
01247  * the same-named parameters of those two functions.
01248  */
01249 svn_error_t *
01250 svn_io_run_cmd(const char *path,
01251                const char *cmd,
01252                const char *const *args,
01253                int *exitcode,
01254                apr_exit_why_e *exitwhy,
01255                svn_boolean_t inherit,
01256                apr_file_t *infile,
01257                apr_file_t *outfile,
01258                apr_file_t *errfile,
01259                apr_pool_t *pool);
01260 
01261 /** Invoke the configured @c diff program, with @a user_args (an array
01262  * of utf8-encoded @a num_user_args arguments) if they are specified
01263  * (that is, if @a user_args is non-NULL), or "-u" if they are not.
01264  * If @a user_args is NULL, the value of @a num_user_args is ignored.
01265  *
01266  * Diff runs in utf8-encoded @a dir, and its exit status is stored in
01267  * @a exitcode, if it is not @c NULL.
01268  *
01269  * If @a label1 and/or @a label2 are not NULL they will be passed to the diff
01270  * process as the arguments of "-L" options.  @a label1 and @a label2 are also
01271  * in utf8, and will be converted to native charset along with the other args.
01272  *
01273  * @a from is the first file passed to diff, and @a to is the second.  The
01274  * stdout of diff will be sent to @a outfile, and the stderr to @a errfile.
01275  *
01276  * @a diff_cmd must be non-NULL.
01277  *
01278  * Do all allocation in @a pool.
01279  * @since New in 1.6.0.
01280  */
01281 svn_error_t *
01282 svn_io_run_diff2(const char *dir,
01283                  const char *const *user_args,
01284                  int num_user_args,
01285                  const char *label1,
01286                  const char *label2,
01287                  const char *from,
01288                  const char *to,
01289                  int *exitcode,
01290                  apr_file_t *outfile,
01291                  apr_file_t *errfile,
01292                  const char *diff_cmd,
01293                  apr_pool_t *pool);
01294 
01295 /** Similar to svn_io_run_diff2() but with @diff_cmd encoded in internal
01296  * encoding used by APR.
01297  *
01298  * @deprecated Provided for backwards compatibility with the 1.5 API. */
01299 SVN_DEPRECATED
01300 svn_error_t *
01301 svn_io_run_diff(const char *dir,
01302                 const char *const *user_args,
01303                 int num_user_args,
01304                 const char *label1,
01305                 const char *label2,
01306                 const char *from,
01307                 const char *to,
01308                 int *exitcode,
01309                 apr_file_t *outfile,
01310                 apr_file_t *errfile,
01311                 const char *diff_cmd,
01312                 apr_pool_t *pool);
01313 
01314 
01315 
01316 /** Invoke the configured @c diff3 program, in utf8-encoded @a dir
01317  * like this:
01318  *
01319  *          diff3 -E -m @a mine @a older @a yours > @a merged
01320  *
01321  * (See the diff3 documentation for details.)
01322  *
01323  * If @a user_args is non-NULL, replace "-E" with the <tt>const char*</tt>
01324  * elements that @a user_args contains.
01325  *
01326  * @a mine, @a older and @a yours are utf8-encoded paths (relative to
01327  * @a dir or absolute) to three files that already exist.
01328  *
01329  * @a merged is an open file handle, and is left open after the merge
01330  * result is written to it. (@a merged should *not* be the same file
01331  * as @a mine, or nondeterministic things may happen!)
01332  *
01333  * @a mine_label, @a older_label, @a yours_label are utf8-encoded label
01334  * parameters for diff3's -L option.  Any of them may be @c NULL, in
01335  * which case the corresponding @a mine, @a older, or @a yours parameter is
01336  * used instead.
01337  *
01338  * Set @a *exitcode to diff3's exit status.  If @a *exitcode is anything
01339  * other than 0 or 1, then return @c SVN_ERR_EXTERNAL_PROGRAM.  (Note the
01340  * following from the diff3 info pages: "An exit status of 0 means
01341  * `diff3' was successful, 1 means some conflicts were found, and 2
01342  * means trouble.")
01343  *
01344  * @a diff3_cmd must be non-NULL.
01345  *
01346  * Do all allocation in @a pool.
01347  *
01348  * @since New in 1.4.
01349  */
01350 svn_error_t *
01351 svn_io_run_diff3_3(int *exitcode,
01352                    const char *dir,
01353                    const char *mine,
01354                    const char *older,
01355                    const char *yours,
01356                    const char *mine_label,
01357                    const char *older_label,
01358                    const char *yours_label,
01359                    apr_file_t *merged,
01360                    const char *diff3_cmd,
01361                    const apr_array_header_t *user_args,
01362                    apr_pool_t *pool);
01363 
01364 /** Similar to svn_io_run_diff3_3(), but with @a diff3_cmd encoded in
01365  * internal encoding used by APR.
01366  *
01367  * @deprecated Provided for backwards compatibility with the 1.5 API.
01368  * @since New in 1.4.
01369  */
01370 SVN_DEPRECATED
01371 svn_error_t *
01372 svn_io_run_diff3_2(int *exitcode,
01373                    const char *dir,
01374                    const char *mine,
01375                    const char *older,
01376                    const char *yours,
01377                    const char *mine_label,
01378                    const char *older_label,
01379                    const char *yours_label,
01380                    apr_file_t *merged,
01381                    const char *diff3_cmd,
01382                    const apr_array_header_t *user_args,
01383                    apr_pool_t *pool);
01384 
01385 /** Similar to svn_io_run_diff3_2(), but with @a user_args set to @c NULL.
01386  *
01387  * @deprecated Provided for backwards compatibility with the 1.3 API.
01388  */
01389 SVN_DEPRECATED
01390 svn_error_t *
01391 svn_io_run_diff3(const char *dir,
01392                  const char *mine,
01393                  const char *older,
01394                  const char *yours,
01395                  const char *mine_label,
01396                  const char *older_label,
01397                  const char *yours_label,
01398                  apr_file_t *merged,
01399                  int *exitcode,
01400                  const char *diff3_cmd,
01401                  apr_pool_t *pool);
01402 
01403 
01404 /** Parse utf8-encoded @a mimetypes_file as a MIME types file (such as
01405  * is provided with Apache HTTP Server), and set @a *type_map to a
01406  * hash mapping <tt>const char *</tt> filename extensions to
01407  * <tt>const char *</tt> MIME types.
01408  *
01409  * @since New in 1.5.
01410  */
01411 svn_error_t *
01412 svn_io_parse_mimetypes_file(apr_hash_t **type_map,
01413                             const char *mimetypes_file,
01414                             apr_pool_t *pool);
01415 
01416 
01417 /** Examine utf8-encoded @a file to determine if it can be described by a
01418  * known (as in, known by this function) Multipurpose Internet Mail
01419  * Extension (MIME) type.  If so, set @a *mimetype to a character string
01420  * describing the MIME type, else set it to @c NULL.
01421  *
01422  * If not @c NULL, @a mimetype_map is a hash mapping <tt>const char *</tt>
01423  * filename extensions to <tt>const char *</tt> MIME types, and is the
01424  * first source consulted regarding @a file's MIME type.
01425  *
01426  * Use @a pool for any necessary allocations.
01427  *
01428  * @since New in 1.5.
01429  */
01430 svn_error_t *
01431 svn_io_detect_mimetype2(const char **mimetype,
01432                         const char *file,
01433                         apr_hash_t *mimetype_map,
01434                         apr_pool_t *pool);
01435 
01436 
01437 /** Like svn_io_detect_mimetype2, but with @a mimetypes_map set to
01438  * @c NULL.
01439  *
01440  * @deprecated Provided for backward compatibility with the 1.4 API
01441  */
01442 SVN_DEPRECATED
01443 svn_error_t *
01444 svn_io_detect_mimetype(const char **mimetype,
01445                        const char *file,
01446                        apr_pool_t *pool);
01447 
01448 
01449 /** Wrapper for apr_file_open().  @a fname is utf8-encoded. */
01450 svn_error_t *
01451 svn_io_file_open(apr_file_t **new_file,
01452                  const char *fname,
01453                  apr_int32_t flag,
01454                  apr_fileperms_t perm,
01455                  apr_pool_t *pool);
01456 
01457 
01458 /** Wrapper for apr_file_close(). */
01459 svn_error_t *
01460 svn_io_file_close(apr_file_t *file,
01461                   apr_pool_t *pool);
01462 
01463 
01464 /** Wrapper for apr_file_getc(). */
01465 svn_error_t *
01466 svn_io_file_getc(char *ch,
01467                  apr_file_t *file,
01468                  apr_pool_t *pool);
01469 
01470 
01471 /** Wrapper for apr_file_info_get(). */
01472 svn_error_t *
01473 svn_io_file_info_get(apr_finfo_t *finfo,
01474                      apr_int32_t wanted,
01475                      apr_file_t *file,
01476                      apr_pool_t *pool);
01477 
01478 
01479 /** Wrapper for apr_file_read(). */
01480 svn_error_t *
01481 svn_io_file_read(apr_file_t *file,
01482                  void *buf,
01483                  apr_size_t *nbytes,
01484                  apr_pool_t *pool);
01485 
01486 
01487 /** Wrapper for apr_file_read_full(). */
01488 svn_error_t *
01489 svn_io_file_read_full(apr_file_t *file,
01490                       void *buf,
01491                       apr_size_t nbytes,
01492                       apr_size_t *bytes_read,
01493                       apr_pool_t *pool);
01494 
01495 
01496 /** Wrapper for apr_file_seek(). */
01497 svn_error_t *
01498 svn_io_file_seek(apr_file_t *file,
01499                  apr_seek_where_t where,
01500                  apr_off_t *offset,
01501                  apr_pool_t *pool);
01502 
01503 
01504 /** Wrapper for apr_file_write(). */
01505 svn_error_t *
01506 svn_io_file_write(apr_file_t *file,
01507                   const void *buf,
01508                   apr_size_t *nbytes,
01509                   apr_pool_t *pool);
01510 
01511 
01512 /** Wrapper for apr_file_write_full(). */
01513 svn_error_t *
01514 svn_io_file_write_full(apr_file_t *file,
01515                        const void *buf,
01516                        apr_size_t nbytes,
01517                        apr_size_t *bytes_written,
01518                        apr_pool_t *pool);
01519 
01520 /**
01521  * Open a unique file in @a dirpath, and write @a nbytes from @a buf to
01522  * the file before closing it.  Return the name of the newly created file
01523  * in @a *tmp_path, allocated in @a pool.
01524  *
01525  * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
01526  * (Note that when using the system-provided temp directory, it may not
01527  * be possibly to atomically rename the resulting file due to cross-device
01528  * issues.)
01529  *
01530  * The file will be deleted according to @a delete_when.
01531  *
01532  * @since New in 1.6.
01533  */
01534 svn_error_t *
01535 svn_io_write_unique(const char **tmp_path,
01536                     const char *dirpath,
01537                     const void *buf,
01538                     apr_size_t nbytes,
01539                     svn_io_file_del_t delete_when,
01540                     apr_pool_t *pool);
01541 
01542 /** Wrapper for apr_file_trunc().
01543   * @since New in 1.6. */
01544 svn_error_t *
01545 svn_io_file_trunc(apr_file_t *file,
01546                   apr_off_t offset,
01547                   apr_pool_t *pool);
01548 
01549 
01550 /** Wrapper for apr_stat().  @a fname is utf8-encoded. */
01551 svn_error_t *
01552 svn_io_stat(apr_finfo_t *finfo,
01553             const char *fname,
01554             apr_int32_t wanted,
01555             apr_pool_t *pool);
01556 
01557 
01558 /** Wrapper for apr_file_rename().  @a from_path and @a to_path are
01559  * utf8-encoded.
01560  */
01561 svn_error_t *
01562 svn_io_file_rename(const char *from_path,
01563                    const char *to_path,
01564                    apr_pool_t *pool);
01565 
01566 
01567 /** Move the file from @a from_path to @a to_path, even across device
01568  * boundaries. Overwrite @a to_path if it exists.
01569  *
01570  * @note This function is different from svn_io_file_rename in that the
01571  * latter fails in the 'across device boundaries' case.
01572  *
01573  * @since New in 1.3.
01574  */
01575 svn_error_t *
01576 svn_io_file_move(const char *from_path,
01577                  const char *to_path,
01578                  apr_pool_t *pool);
01579 
01580 
01581 /** Wrapper for apr_dir_make().  @a path is utf8-encoded. */
01582 svn_error_t *
01583 svn_io_dir_make(const char *path,
01584                 apr_fileperms_t perm,
01585                 apr_pool_t *pool);
01586 
01587 /** Same as svn_io_dir_make(), but sets the hidden attribute on the
01588     directory on systems that support it. */
01589 svn_error_t *
01590 svn_io_dir_make_hidden(const char *path,
01591                        apr_fileperms_t perm,
01592                        apr_pool_t *pool);
01593 
01594 /**
01595  * Same as svn_io_dir_make(), but attempts to set the sgid on the
01596  * directory on systems that support it.  Does not return an error if
01597  * the attempt to set the sgid bit fails.  On Unix filesystems,
01598  * setting the sgid bit on a directory ensures that files and
01599  * subdirectories created within inherit group ownership from the
01600  * parent instead of from the primary gid.
01601  *
01602  * @since New in 1.1.
01603  */
01604 svn_error_t *
01605 svn_io_dir_make_sgid(const char *path,
01606                      apr_fileperms_t perm,
01607                      apr_pool_t *pool);
01608 
01609 /** Wrapper for apr_dir_open().  @a dirname is utf8-encoded. */
01610 svn_error_t *
01611 svn_io_dir_open(apr_dir_t **new_dir,
01612                 const char *dirname,
01613                 apr_pool_t *pool);
01614 
01615 
01616 /** Wrapper for apr_dir_remove().  @a dirname is utf8-encoded.
01617  * @note This function has this name to avoid confusion with
01618  * svn_io_remove_dir2(), which is recursive.
01619  */
01620 svn_error_t *
01621 svn_io_dir_remove_nonrecursive(const char *dirname,
01622                                apr_pool_t *pool);
01623 
01624 
01625 /** Wrapper for apr_dir_read().  Ensures that @a finfo->name is
01626  * utf8-encoded, which means allocating @a finfo->name in @a pool,
01627  * which may or may not be the same as @a finfo's pool.  Use @a pool
01628  * for error allocation as well.
01629  */
01630 svn_error_t *
01631 svn_io_dir_read(apr_finfo_t *finfo,
01632                 apr_int32_t wanted,
01633                 apr_dir_t *thedir,
01634                 apr_pool_t *pool);
01635 
01636 
01637 
01638 /** Version/format files.
01639  *
01640  * @defgroup svn_io_format_files Version/format files
01641  * @{
01642  */
01643 
01644 /** Set @a *version to the integer that starts the file at @a path.  If the
01645  * file does not begin with a series of digits followed by a newline,
01646  * return the error @c SVN_ERR_BAD_VERSION_FILE_FORMAT.  Use @a pool for
01647  * all allocations.
01648  */
01649 svn_error_t *
01650 svn_io_read_version_file(int *version,
01651                          const char *path,
01652                          apr_pool_t *pool);
01653 
01654 /** Create (or overwrite) the file at @a path with new contents,
01655  * formatted as a non-negative integer @a version followed by a single
01656  * newline.  On successful completion the file will be read-only.  Use
01657  * @a pool for all allocations.
01658  */
01659 svn_error_t *
01660 svn_io_write_version_file(const char *path,
01661                           int version,
01662                           apr_pool_t *pool);
01663 
01664 /** @} */
01665 
01666 #ifdef __cplusplus
01667 }
01668 #endif /* __cplusplus */
01669 
01670 #endif /* SVN_IO_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines