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