- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# 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 svn_error_t *
    01069 svn_stream_skip(svn_stream_t *stream,
    01070                 apr_size_t len);
    01071
    01072 /** Write to a generic stream. @see svn_stream_t. */
    01073 svn_error_t *
    01074 svn_stream_write(svn_stream_t *stream,
    01075                  const char *data,
    01076                  apr_size_t *len);
    01077
    01078 /** Close a generic stream. @see svn_stream_t. */
    01079 svn_error_t *
    01080 svn_stream_close(svn_stream_t *stream);
    01081
    01082 /** Reset a generic stream back to its origin. E.g. On a file this would be
    01083  * implemented as a seek to position 0).  This function returns a
    01084  * #SVN_ERR_STREAM_RESET_NOT_SUPPORTED error when the stream doesn't
    01085  * implement resetting.
    01086  *
    01087  * @since New in 1.7.
    01088  */
    01089 svn_error_t *
    01090 svn_stream_reset(svn_stream_t *stream);
    01091
    01092 /** Returns @c TRUE if the generic @a stream supports svn_stream_mark().
    01093  *
    01094  * @see svn_stream_mark()
    01095  * @since New in 1.7.
    01096  */
    01097 svn_boolean_t
    01098 svn_stream_supports_mark(svn_stream_t *stream);
    01099
    01100 /** Set a @a mark at the current position of a generic @a stream,
    01101  * which can later be sought back to using svn_stream_seek().
    01102  * The @a mark is allocated in @a pool.
    01103  *
    01104  * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error
    01105  * if the stream doesn't implement seeking.
    01106  *
    01107  * @see svn_stream_seek()
    01108  * @since New in 1.7.
    01109  */
    01110 svn_error_t *
    01111 svn_stream_mark(svn_stream_t *stream,
    01112                 svn_stream_mark_t **mark,
    01113                 apr_pool_t *pool);
    01114
    01115 /** Seek to a @a mark in a generic @a stream.
    01116  * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error
    01117  * if the stream doesn't implement seeking. Passing NULL as @a mark,
    01118  * seeks to the start of the stream.
    01119  *
    01120  * @see svn_stream_mark()
    01121  * @since New in 1.7.
    01122  */
    01123 svn_error_t *
    01124 svn_stream_seek(svn_stream_t *stream, const svn_stream_mark_t *mark);
    01125
    01126 /** Return a writable stream which, when written to, writes to both of the
    01127  * underlying streams.  Both of these streams will be closed upon closure of
    01128  * the returned stream; use svn_stream_disown() if this is not the desired
    01129  * behavior.  One or both of @a out1 and @a out2 may be @c NULL.  If both are
    01130  * @c NULL, @c NULL is returned.
    01131  *
    01132  * @since New in 1.7.
    01133  */
    01134 svn_stream_t *
    01135 svn_stream_tee(svn_stream_t *out1,
    01136                svn_stream_t *out2,
    01137                apr_pool_t *pool);
    01138
    01139
    01140 /** Write to @a stream using a printf-style @a fmt specifier, passed through
    01141  * apr_psprintf() using memory from @a pool.
    01142  */
    01143 svn_error_t *
    01144 svn_stream_printf(svn_stream_t *stream,
    01145                   apr_pool_t *pool,
    01146                   const char *fmt,
    01147                   ...)
    01148        __attribute__((format(printf, 3, 4)));
    01149
    01150 /** Write to @a stream using a printf-style @a fmt specifier, passed through
    01151  * apr_psprintf() using memory from @a pool.  The resulting string
    01152  * will be translated to @a encoding before it is sent to @a stream.
    01153  *
    01154  * @note Use @c APR_LOCALE_CHARSET to translate to the encoding of the
    01155  * current locale.
    01156  *
    01157  * @since New in 1.3.
    01158  */
    01159 svn_error_t *
    01160 svn_stream_printf_from_utf8(svn_stream_t *stream,
    01161                             const char *encoding,
    01162                             apr_pool_t *pool,
    01163                             const char *fmt,
    01164                             ...)
    01165        __attribute__((format(printf, 4, 5)));
    01166
    01167 /** Allocate @a *stringbuf in @a pool, and read into it one line (terminated
    01168  * by @a eol) from @a stream. The line-terminator is read from the stream,
    01169  * but is not added to the end of the stringbuf.  Instead, the stringbuf
    01170  * ends with a usual '\\0'.
    01171  *
    01172  * If @a stream runs out of bytes before encountering a line-terminator,
    01173  * then set @a *eof to @c TRUE, otherwise set @a *eof to FALSE.
    01174  */
    01175 svn_error_t *
    01176 svn_stream_readline(svn_stream_t *stream,
    01177                     svn_stringbuf_t **stringbuf,
    01178                     const char *eol,
    01179                     svn_boolean_t *eof,
    01180                     apr_pool_t *pool);
    01181
    01182 /**
    01183  * Read the contents of the readable stream @a from and write them to the
    01184  * writable stream @a to calling @a cancel_func before copying each chunk.
    01185  *
    01186  * @a cancel_func may be @c NULL.
    01187  *
    01188  * @note both @a from and @a to will be closed upon successful completion of
    01189  * the copy (but an error may still be returned, based on trying to close
    01190  * the two streams). If the closure is not desired, then you can use
    01191  * svn_stream_disown() to protect either or both of the streams from
    01192  * being closed.
    01193  *
    01194  * @since New in 1.6.
    01195  */
    01196 svn_error_t *
    01197 svn_stream_copy3(svn_stream_t *from,
    01198                  svn_stream_t *to,
    01199                  svn_cancel_func_t cancel_func,
    01200                  void *cancel_baton,
    01201                  apr_pool_t *pool);
    01202
    01203 /**
    01204  * Same as svn_stream_copy3() but the streams are not closed.
    01205  *
    01206  * @since New in 1.5.
    01207  * @deprecated Provided for backward compatibility with the 1.5 API.
    01208  */
    01209 SVN_DEPRECATED
    01210 svn_error_t *
    01211 svn_stream_copy2(svn_stream_t *from,
    01212                  svn_stream_t *to,
    01213                  svn_cancel_func_t cancel_func,
    01214                  void *cancel_baton,
    01215                  apr_pool_t *pool);
    01216
    01217 /**
    01218  * Same as svn_stream_copy3(), but without the cancellation function
    01219  * or stream closing.
    01220  *
    01221  * @since New in 1.1.
    01222  * @deprecated Provided for backward compatibility with the 1.4 API.
    01223  */
    01224 SVN_DEPRECATED
    01225 svn_error_t *
    01226 svn_stream_copy(svn_stream_t *from,
    01227                 svn_stream_t *to,
    01228                 apr_pool_t *pool);
    01229
    01230
    01231 /** Set @a *same to TRUE if @a stream1 and @a stream2 have the same
    01232  * contents, else set it to FALSE.
    01233  *
    01234  * Both streams will be closed before this function returns (regardless of
    01235  * the result, or any possible error).
    01236  *
    01237  * Use @a scratch_pool for temporary allocations.
    01238  *
    01239  * @since New in 1.7.
    01240  */
    01241 svn_error_t *
    01242 svn_stream_contents_same2(svn_boolean_t *same,
    01243                           svn_stream_t *stream1,
    01244                           svn_stream_t *stream2,
    01245                           apr_pool_t *pool);
    01246
    01247
    01248 /**
    01249  * Same as svn_stream_contents_same2(), but the streams will not be closed.
    01250  *
    01251  * @since New in 1.4.
    01252  * @deprecated Provided for backward compatibility with the 1.6 API.
    01253  */
    01254 SVN_DEPRECATED
    01255 svn_error_t *
    01256 svn_stream_contents_same(svn_boolean_t *same,
    01257                          svn_stream_t *stream1,
    01258                          svn_stream_t *stream2,
    01259                          apr_pool_t *pool);
    01260
    01261
    01262 /** Read the contents of @a stream into memory, returning the data in
    01263  * @a result. The stream will be closed when it has been successfully and
    01264  * completely read.
    01265  *
    01266  * The returned memory is allocated in @a result_pool, and any temporary
    01267  * allocations are performed in @a scratch_pool.
    01268  *
    01269  * @note due to memory pseudo-reallocation behavior (due to pools), this
    01270  *   can be a memory-intensive operation for large files.
    01271  *
    01272  * @since New in 1.6
    01273  */
    01274 svn_error_t *
    01275 svn_string_from_stream(svn_string_t **result,
    01276                        svn_stream_t *stream,
    01277                        apr_pool_t *result_pool,
    01278                        apr_pool_t *scratch_pool);
    01279
    01280
    01281 /** @} */
    01282
    01283 /** Set @a *result to a string containing the contents of @a
    01284  * filename, which is either "-" (indicating that stdin should be
    01285  * read) or the utf8-encoded path of a real file.
    01286  *
    01287  * @warning Callers should be aware of possible unexpected results
    01288  * when using this function to read from stdin where additional
    01289  * stdin-reading processes abound.  For example, if a program tries
    01290  * both to invoke an external editor and to read from stdin, stdin
    01291  * could be trashed and the editor might act funky or die outright.
    01292  *
    01293  * @note due to memory pseudo-reallocation behavior (due to pools), this
    01294  *   can be a memory-intensive operation for large files.
    01295  *
    01296  * @since New in 1.5.
    01297  */
    01298 svn_error_t *
    01299 svn_stringbuf_from_file2(svn_stringbuf_t **result,
    01300                          const char *filename,
    01301                          apr_pool_t *pool);
    01302
    01303 /** Similar to svn_stringbuf_from_file2(), except that if @a filename
    01304  * is "-", return the error #SVN_ERR_UNSUPPORTED_FEATURE and don't
    01305  * touch @a *result.
    01306  *
    01307  * @deprecated Provided for backwards compatibility with the 1.4 API.
    01308  */
    01309 SVN_DEPRECATED
    01310 svn_error_t *
    01311 svn_stringbuf_from_file(svn_stringbuf_t **result,
    01312                         const char *filename,
    01313                         apr_pool_t *pool);
    01314
    01315 /** Sets @a *result to a string containing the contents of the already opened
    01316  * @a file.  Reads from the current position in file to the end.  Does not
    01317  * close the file or reset the cursor position.
    01318  *
    01319  * @note due to memory pseudo-reallocation behavior (due to pools), this
    01320  *   can be a memory-intensive operation for large files.
    01321  */
    01322 svn_error_t *
    01323 svn_stringbuf_from_aprfile(svn_stringbuf_t **result,
    01324                            apr_file_t *file,
    01325                            apr_pool_t *pool);
    01326
    01327 /** Remove file @a path, a utf8-encoded path.  This wraps apr_file_remove(),
    01328  * converting any error to a Subversion error. If @a ignore_enoent is TRUE, and
    01329  * the file is not present (APR_STATUS_IS_ENOENT returns TRUE), then no
    01330  * error will be returned.
    01331  *
    01332  * The file will be removed even if it is not writable.  (On Windows and
    01333  * OS/2, this function first clears the file's read-only bit.)
    01334  *
    01335  * @since New in 1.7.
    01336  */
    01337 svn_error_t *
    01338 svn_io_remove_file2(const char *path,
    01339                     svn_boolean_t ignore_enoent,
    01340                     apr_pool_t *scratch_pool);
    01341
    01342 /** Similar to svn_io_remove_file2(), except with @a ignore_enoent set to FALSE.
    01343  *
    01344  * @deprecated Provided for backwards compatibility with the 1.6 API.
    01345  */
    01346 SVN_DEPRECATED
    01347 svn_error_t *
    01348 svn_io_remove_file(const char *path,
    01349                    apr_pool_t *pool);
    01350
    01351 /** Recursively remove directory @a path.  @a path is utf8-encoded.
    01352  * If @a ignore_enoent is @c TRUE, don't fail if the target directory
    01353  * doesn't exist.  Use @a pool for temporary allocations.
    01354  *
    01355  * Because recursive delete of a directory tree can be a lengthy operation,
    01356  * provide @a cancel_func and @a cancel_baton for interruptibility.
    01357  *
    01358  * @since New in 1.5.
    01359  */
    01360 svn_error_t *
    01361 svn_io_remove_dir2(const char *path,
    01362                    svn_boolean_t ignore_enoent,
    01363                    svn_cancel_func_t cancel_func,
    01364                    void *cancel_baton,
    01365                    apr_pool_t *pool);
    01366
    01367 /** Similar to svn_io_remove_dir2(), but with @a ignore_enoent set to
    01368  * @c FALSE and @a cancel_func and @a cancel_baton set to @c NULL.
    01369  *
    01370  * @deprecated Provided for backward compatibility with the 1.4 API
    01371  */
    01372 SVN_DEPRECATED
    01373 svn_error_t *
    01374 svn_io_remove_dir(const char *path,
    01375                   apr_pool_t *pool);
    01376
    01377 /** Read all of the disk entries in directory @a path, a utf8-encoded
    01378  * path.  Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
    01379  * undefined non-NULL values, allocated in @a pool.
    01380  *
    01381  * @note The `.' and `..' directories normally returned by
    01382  * apr_dir_read() are NOT returned in the hash.
    01383  *
    01384  * @since New in 1.4.
    01385  * @deprecated Provided for backward compatibility with the 1.6 API.
    01386  */
    01387 SVN_DEPRECATED
    01388 svn_error_t *
    01389 svn_io_get_dir_filenames(apr_hash_t **dirents,
    01390                          const char *path,
    01391                          apr_pool_t *pool);
    01392
    01393 /** Read all of the disk entries in directory @a path, a utf8-encoded
    01394  * path.  Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
    01395  * #svn_io_dirent2_t structures, allocated in @a pool.
    01396  *
    01397  * If @a only_check_type is set to @c TRUE, only the kind and special
    01398  * fields of the svn_io_dirent2_t are filled.
    01399  *
    01400  * @note The `.' and `..' directories normally returned by
    01401  * apr_dir_read() are NOT returned in the hash.
    01402  *
    01403  * @note The kind field in the @a dirents is set according to the mapping
    01404  *       as documented for svn_io_check_path().
    01405  *
    01406  * @since New in 1.7.
    01407  */
    01408 svn_error_t *
    01409 svn_io_get_dirents3(apr_hash_t **dirents,
    01410                     const char *path,
    01411                     svn_boolean_t only_check_type,
    01412                     apr_pool_t *result_pool,
    01413                     apr_pool_t *scratch_pool);
    01414
    01415
    01416 /** Similar to svn_io_get_dirents3, but returns a mapping to svn_io_dirent_t
    01417  * structures instead of svn_io_dirent2_t and with only a single pool.
    01418  *
    01419  * @since New in 1.3.
    01420  * @deprecated Provided for backward compatibility with the 1.6 API.
    01421  */
    01422 SVN_DEPRECATED
    01423 svn_error_t *
    01424 svn_io_get_dirents2(apr_hash_t **dirents,
    01425                     const char *path,
    01426                     apr_pool_t *pool);
    01427
    01428 /** Similar to svn_io_get_dirents2(), but @a *dirents is a hash table
    01429  * with #svn_node_kind_t values.
    01430  *
    01431  * @deprecated Provided for backwards compatibility with the 1.2 API.
    01432  */
    01433 SVN_DEPRECATED
    01434 svn_error_t *
    01435 svn_io_get_dirents(apr_hash_t **dirents,
    01436                    const char *path,
    01437                    apr_pool_t *pool);
    01438
    01439 /** Create a svn_io_dirent2_t instance for path. Specialized variant of
    01440  * svn_io_stat() that directly translates node_kind and special.
    01441  *
    01442  * If @a ignore_enoent is set to @c TRUE, set *dirent_p->kind to
    01443  * svn_node_none instead of returning an error.
    01444  *
    01445  * @since New in 1.7.
    01446  */
    01447 svn_error_t *
    01448 svn_io_stat_dirent(const svn_io_dirent2_t **dirent_p,
    01449                    const char *path,
    01450                    svn_boolean_t ignore_enoent,
    01451                    apr_pool_t *result_pool,
    01452                    apr_pool_t *scratch_pool);
    01453
    01454
    01455 /** Callback function type for svn_io_dir_walk() */
    01456 typedef svn_error_t * (*svn_io_walk_func_t)(void *baton,
    01457                                             const char *path,
    01458                                             const apr_finfo_t *finfo,
    01459                                             apr_pool_t *pool);
    01460
    01461 /** Recursively walk the directory rooted at @a dirname, a
    01462  * utf8-encoded path, invoking @a walk_func (with @a walk_baton) for
    01463  * each item in the tree.  For a given directory, invoke @a walk_func
    01464  * on the directory itself before invoking it on any children thereof.
    01465  *
    01466  * Deliver to @a walk_func the information specified by @a wanted,
    01467  * which is a combination of @c APR_FINFO_* flags, plus the
    01468  * information specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME.
    01469  *
    01470  * Use @a pool for all allocations.
    01471  *
    01472  * @note This function does not currently pass all file types to @a
    01473  * walk_func -- only APR_DIR, APR_REG, and APR_LNK.  We reserve the
    01474  * right to pass additional file types through this interface in the
    01475  * future, though, so implementations of this callback should
    01476  * explicitly test FINFO->filetype.  See the APR library's
    01477  * apr_filetype_e enum for the various filetypes and their meanings.
    01478  *
    01479  * @since New in 1.7.
    01480  */
    01481 svn_error_t *
    01482 svn_io_dir_walk2(const char *dirname,
    01483                  apr_int32_t wanted,
    01484                  svn_io_walk_func_t walk_func,
    01485                  void *walk_baton,
    01486                  apr_pool_t *pool);
    01487
    01488 /** Similar to svn_io_dir_walk(), but only calls @a walk_func for
    01489  * files of type APR_DIR (directory) and APR_REG (regular file).
    01490  *
    01491  * @deprecated Provided for backwards compatibility with the 1.6 API.
    01492  */
    01493 SVN_DEPRECATED
    01494 svn_error_t *
    01495 svn_io_dir_walk(const char *dirname,
    01496                 apr_int32_t wanted,
    01497                 svn_io_walk_func_t walk_func,
    01498                 void *walk_baton,
    01499                 apr_pool_t *pool);
    01500
    01501 /**
    01502  * Start @a cmd with @a args, using utf8-encoded @a path as working
    01503  * directory.  Return the process handle for the invoked program in @a
    01504  * *cmd_proc.
    01505  *
    01506  * If @a infile_pipe is TRUE, connect @a cmd's stdin to a pipe;
    01507  * otherwise, connect it to @a infile (which may be NULL).  If
    01508  * @a outfile_pipe is TRUE, connect @a cmd's stdout to a pipe; otherwise,
    01509  * connect it to @a outfile (which may be NULL).  If @a errfile_pipe
    01510  * is TRUE, connect @a cmd's stderr to a pipe; otherwise, connect it
    01511  * to @a errfile (which may be NULL).  (Callers must pass FALSE for
    01512  * each of these boolean values for which the corresponding file
    01513  * handle is non-NULL.)
    01514  *
    01515  * @a args is a list of utf8-encoded <tt>const char *</tt> arguments,
    01516  * terminated by @c NULL.  @a args[0] is the name of the program, though it
    01517  * need not be the same as @a cmd.
    01518  *
    01519  * If @a inherit is TRUE, the invoked program inherits its environment from
    01520  * the caller and @a cmd, if not absolute, is searched for in PATH.
    01521  * Otherwise, the invoked program runs with an empty environment and @a cmd
    01522  * must be an absolute path.
    01523  *
    01524  * @note On some platforms, failure to execute @a cmd in the child process
    01525  * will result in error output being written to @a errfile, if non-NULL, and
    01526  * a non-zero exit status being returned to the parent process.
    01527  *
    01528  * @since New in 1.7.
    01529  */
    01530 svn_error_t *svn_io_start_cmd2(apr_proc_t *cmd_proc,
    01531                                const char *path,
    01532                                const char *cmd,
    01533                                const char *const *args,
    01534                                svn_boolean_t inherit,
    01535                                svn_boolean_t infile_pipe,
    01536                                apr_file_t *infile,
    01537                                svn_boolean_t outfile_pipe,
    01538                                apr_file_t *outfile,
    01539                                svn_boolean_t errfile_pipe,
    01540                                apr_file_t *errfile,
    01541                                apr_pool_t *pool);
    01542
    01543 /**
    01544  * Similar to svn_io_start_cmd2() but with @a infile_pipe, @a
    01545  * outfile_pipe, and @a errfile_pipe always FALSE.
    01546  *
    01547  * @deprecated Provided for backward compatibility with the 1.6 API
    01548  * @since New in 1.3.
    01549  */
    01550 SVN_DEPRECATED
    01551 svn_error_t *
    01552 svn_io_start_cmd(apr_proc_t *cmd_proc,
    01553                  const char *path,
    01554                  const char *cmd,
    01555                  const char *const *args,
    01556                  svn_boolean_t inherit,
    01557                  apr_file_t *infile,
    01558                  apr_file_t *outfile,
    01559                  apr_file_t *errfile,
    01560                  apr_pool_t *pool);
    01561
    01562 /**
    01563  * Wait for the process @a *cmd_proc to complete and optionally retrieve
    01564  * its exit code.  @a cmd is used only in error messages.
    01565  *
    01566  * If @a exitcode is not NULL, set @a *exitcode to the exit code of the
    01567  * process and do not consider any exit code to be an error.  If @a exitcode
    01568  * is NULL, then if the exit code of the process is non-zero then return an
    01569  * #SVN_ERR_EXTERNAL_PROGRAM error.
    01570  *
    01571  * If @a exitwhy is not NULL, set @a *exitwhy to indicate why the process
    01572  * terminated and do not consider any reason to be an error.  If @a exitwhy
    01573  * is NULL, then if the termination reason is not @c APR_PROC_CHECK_EXIT()
    01574  * then return an #SVN_ERR_EXTERNAL_PROGRAM error.
    01575  *
    01576  * @since New in 1.3.
    01577  */
    01578 svn_error_t *
    01579 svn_io_wait_for_cmd(apr_proc_t *cmd_proc,
    01580                     const char *cmd,
    01581                     int *exitcode,
    01582                     apr_exit_why_e *exitwhy,
    01583                     apr_pool_t *pool);
    01584
    01585 /** Run a command to completion, by first calling svn_io_start_cmd() and
    01586  * then calling svn_io_wait_for_cmd().  The parameters correspond to
    01587  * the same-named parameters of those two functions.
    01588  */
    01589 svn_error_t *
    01590 svn_io_run_cmd(const char *path,
    01591                const char *cmd,
    01592                const char *const *args,
    01593                int *exitcode,
    01594                apr_exit_why_e *exitwhy,
    01595                svn_boolean_t inherit,
    01596                apr_file_t *infile,
    01597                apr_file_t *outfile,
    01598                apr_file_t *errfile,
    01599                apr_pool_t *pool);
    01600
    01601 /** Invoke the configured @c diff program, with @a user_args (an array
    01602  * of utf8-encoded @a num_user_args arguments) if they are specified
    01603  * (that is, if @a user_args is non-NULL), or "-u" if they are not.
    01604  * If @a user_args is NULL, the value of @a num_user_args is ignored.
    01605  *
    01606  * Diff runs in utf8-encoded @a dir, and its exit status is stored in
    01607  * @a exitcode, if it is not @c NULL.
    01608  *
    01609  * If @a label1 and/or @a label2 are not NULL they will be passed to the diff
    01610  * process as the arguments of "-L" options.  @a label1 and @a label2 are also
    01611  * in utf8, and will be converted to native charset along with the other args.
    01612  *
    01613  * @a from is the first file passed to diff, and @a to is the second.  The
    01614  * stdout of diff will be sent to @a outfile, and the stderr to @a errfile.
    01615  *
    01616  * @a diff_cmd must be non-NULL.
    01617  *
    01618  * Do all allocation in @a pool.
    01619  * @since New in 1.6.0.
    01620  */
    01621 svn_error_t *
    01622 svn_io_run_diff2(const char *dir,
    01623                  const char *const *user_args,
    01624                  int num_user_args,
    01625                  const char *label1,
    01626                  const char *label2,
    01627                  const char *from,
    01628                  const char *to,
    01629                  int *exitcode,
    01630                  apr_file_t *outfile,
    01631                  apr_file_t *errfile,
    01632                  const char *diff_cmd,
    01633                  apr_pool_t *pool);
    01634
    01635 /** Similar to svn_io_run_diff2() but with @a diff_cmd encoded in internal
    01636  * encoding used by APR.
    01637  *
    01638  * @deprecated Provided for backwards compatibility with the 1.5 API. */
    01639 SVN_DEPRECATED
    01640 svn_error_t *
    01641 svn_io_run_diff(const char *dir,
    01642                 const char *const *user_args,
    01643                 int num_user_args,
    01644                 const char *label1,
    01645                 const char *label2,
    01646                 const char *from,
    01647                 const char *to,
    01648                 int *exitcode,
    01649                 apr_file_t *outfile,
    01650                 apr_file_t *errfile,
    01651                 const char *diff_cmd,
    01652                 apr_pool_t *pool);
    01653
    01654
    01655
    01656 /** Invoke the configured @c diff3 program, in utf8-encoded @a dir
    01657  * like this:
    01658  *
    01659  *          diff3 -E -m @a mine @a older @a yours > @a merged
    01660  *
    01661  * (See the diff3 documentation for details.)
    01662  *
    01663  * If @a user_args is non-NULL, replace "-E" with the <tt>const char*</tt>
    01664  * elements that @a user_args contains.
    01665  *
    01666  * @a mine, @a older and @a yours are utf8-encoded paths (relative to
    01667  * @a dir or absolute) to three files that already exist.
    01668  *
    01669  * @a merged is an open file handle, and is left open after the merge
    01670  * result is written to it. (@a merged should *not* be the same file
    01671  * as @a mine, or nondeterministic things may happen!)
    01672  *
    01673  * @a mine_label, @a older_label, @a yours_label are utf8-encoded label
    01674  * parameters for diff3's -L option.  Any of them may be @c NULL, in
    01675  * which case the corresponding @a mine, @a older, or @a yours parameter is
    01676  * used instead.
    01677  *
    01678  * Set @a *exitcode to diff3's exit status.  If @a *exitcode is anything
    01679  * other than 0 or 1, then return #SVN_ERR_EXTERNAL_PROGRAM.  (Note the
    01680  * following from the diff3 info pages: "An exit status of 0 means
    01681  * `diff3' was successful, 1 means some conflicts were found, and 2
    01682  * means trouble.")
    01683  *
    01684  * @a diff3_cmd must be non-NULL.
    01685  *
    01686  * Do all allocation in @a pool.
    01687  *
    01688  * @since New in 1.4.
    01689  */
    01690 svn_error_t *
    01691 svn_io_run_diff3_3(int *exitcode,
    01692                    const char *dir,
    01693                    const char *mine,
    01694                    const char *older,
    01695                    const char *yours,
    01696                    const char *mine_label,
    01697                    const char *older_label,
    01698                    const char *yours_label,
    01699                    apr_file_t *merged,
    01700                    const char *diff3_cmd,
    01701                    const apr_array_header_t *user_args,
    01702                    apr_pool_t *pool);
    01703
    01704 /** Similar to svn_io_run_diff3_3(), but with @a diff3_cmd encoded in
    01705  * internal encoding used by APR.
    01706  *
    01707  * @deprecated Provided for backwards compatibility with the 1.5 API.
    01708  * @since New in 1.4.
    01709  */
    01710 SVN_DEPRECATED
    01711 svn_error_t *
    01712 svn_io_run_diff3_2(int *exitcode,
    01713                    const char *dir,
    01714                    const char *mine,
    01715                    const char *older,
    01716                    const char *yours,
    01717                    const char *mine_label,
    01718                    const char *older_label,
    01719                    const char *yours_label,
    01720                    apr_file_t *merged,
    01721                    const char *diff3_cmd,
    01722                    const apr_array_header_t *user_args,
    01723                    apr_pool_t *pool);
    01724
    01725 /** Similar to svn_io_run_diff3_2(), but with @a user_args set to @c NULL.
    01726  *
    01727  * @deprecated Provided for backwards compatibility with the 1.3 API.
    01728  */
    01729 SVN_DEPRECATED
    01730 svn_error_t *
    01731 svn_io_run_diff3(const char *dir,
    01732                  const char *mine,
    01733                  const char *older,
    01734                  const char *yours,
    01735                  const char *mine_label,
    01736                  const char *older_label,
    01737                  const char *yours_label,
    01738                  apr_file_t *merged,
    01739                  int *exitcode,
    01740                  const char *diff3_cmd,
    01741                  apr_pool_t *pool);
    01742
    01743
    01744 /** Parse utf8-encoded @a mimetypes_file as a MIME types file (such as
    01745  * is provided with Apache HTTP Server), and set @a *type_map to a
    01746  * hash mapping <tt>const char *</tt> filename extensions to
    01747  * <tt>const char *</tt> MIME types.
    01748  *
    01749  * @since New in 1.5.
    01750  */
    01751 svn_error_t *
    01752 svn_io_parse_mimetypes_file(apr_hash_t **type_map,
    01753                             const char *mimetypes_file,
    01754                             apr_pool_t *pool);
    01755
    01756
    01757 /** Examine utf8-encoded @a file to determine if it can be described by a
    01758  * known (as in, known by this function) Multipurpose Internet Mail
    01759  * Extension (MIME) type.  If so, set @a *mimetype to a character string
    01760  * describing the MIME type, else set it to @c NULL.
    01761  *
    01762  * If not @c NULL, @a mimetype_map is a hash mapping <tt>const char *</tt>
    01763  * filename extensions to <tt>const char *</tt> MIME types, and is the
    01764  * first source consulted regarding @a file's MIME type.
    01765  *
    01766  * Use @a pool for any necessary allocations.
    01767  *
    01768  * @since New in 1.5.
    01769  */
    01770 svn_error_t *
    01771 svn_io_detect_mimetype2(const char **mimetype,
    01772                         const char *file,
    01773                         apr_hash_t *mimetype_map,
    01774                         apr_pool_t *pool);
    01775
    01776
    01777 /** Like svn_io_detect_mimetype2, but with @a mimetypes_map set to
    01778  * @c NULL.
    01779  *
    01780  * @deprecated Provided for backward compatibility with the 1.4 API
    01781  */
    01782 SVN_DEPRECATED
    01783 svn_error_t *
    01784 svn_io_detect_mimetype(const char **mimetype,
    01785                        const char *file,
    01786                        apr_pool_t *pool);
    01787
    01788
    01789 /** Examine up to @a len bytes of data in @a buf to determine if the
    01790  * can be considered binary data, in which case return TRUE.
    01791  * If the data can be considered plain-text data, return FALSE.
    01792  *
    01793  * @since New in 1.7.
    01794  */
    01795 svn_boolean_t
    01796 svn_io_is_binary_data(const void *buf, apr_size_t len);
    01797
    01798
    01799 /** Wrapper for apr_file_open().  @a fname is utf8-encoded. */
    01800 svn_error_t *
    01801 svn_io_file_open(apr_file_t **new_file,
    01802                  const char *fname,
    01803                  apr_int32_t flag,
    01804                  apr_fileperms_t perm,
    01805                  apr_pool_t *pool);
    01806
    01807
    01808 /** Wrapper for apr_file_close(). */
    01809 svn_error_t *
    01810 svn_io_file_close(apr_file_t *file,
    01811                   apr_pool_t *pool);
    01812
    01813
    01814 /** Wrapper for apr_file_getc(). */
    01815 svn_error_t *
    01816 svn_io_file_getc(char *ch,
    01817                  apr_file_t *file,
    01818                  apr_pool_t *pool);
    01819
    01820
    01821 /** Wrapper for apr_file_putc().
    01822   * @since New in 1.7
    01823   */
    01824 svn_error_t *
    01825 svn_io_file_putc(char ch,
    01826                  apr_file_t *file,
    01827                  apr_pool_t *pool);
    01828
    01829
    01830 /** Wrapper for apr_file_info_get(). */
    01831 svn_error_t *
    01832 svn_io_file_info_get(apr_finfo_t *finfo,
    01833                      apr_int32_t wanted,
    01834                      apr_file_t *file,
    01835                      apr_pool_t *pool);
    01836
    01837
    01838 /** Wrapper for apr_file_read(). */
    01839 svn_error_t *
    01840 svn_io_file_read(apr_file_t *file,
    01841                  void *buf,
    01842                  apr_size_t *nbytes,
    01843                  apr_pool_t *pool);
    01844
    01845
    01846 /** Wrapper for apr_file_read_full().
    01847  *
    01848  * If @a hit_eof is not NULL, EOF will be indicated there and no
    01849  * svn_error_t error object will be created upon EOF.
    01850  *
    01851  * @since New in 1.7
    01852  */
    01853 svn_error_t *
    01854 svn_io_file_read_full2(apr_file_t *file,
    01855                        void *buf,
    01856                        apr_size_t nbytes,
    01857                        apr_size_t *bytes_read,
    01858                        svn_boolean_t *hit_eof,
    01859                        apr_pool_t *pool);
    01860
    01861
    01862 /** Similar to svn_io_file_read_full2 with hit_eof being set
    01863  * to @c NULL.
    01864  *
    01865  * @deprecated Provided for backward compatibility with the 1.6 API
    01866  */
    01867 SVN_DEPRECATED
    01868 svn_error_t *
    01869 svn_io_file_read_full(apr_file_t *file,
    01870                       void *buf,
    01871                       apr_size_t nbytes,
    01872                       apr_size_t *bytes_read,
    01873                       apr_pool_t *pool);
    01874
    01875
    01876 /** Wrapper for apr_file_seek(). */
    01877 svn_error_t *
    01878 svn_io_file_seek(apr_file_t *file,
    01879                  apr_seek_where_t where,
    01880                  apr_off_t *offset,
    01881                  apr_pool_t *pool);
    01882
    01883
    01884 /** Wrapper for apr_file_write(). */
    01885 svn_error_t *
    01886 svn_io_file_write(apr_file_t *file,
    01887                   const void *buf,
    01888                   apr_size_t *nbytes,
    01889                   apr_pool_t *pool);
    01890
    01891
    01892 /** Wrapper for apr_file_write_full(). */
    01893 svn_error_t *
    01894 svn_io_file_write_full(apr_file_t *file,
    01895                        const void *buf,
    01896                        apr_size_t nbytes,
    01897                        apr_size_t *bytes_written,
    01898                        apr_pool_t *pool);
    01899
    01900 /**
    01901  * Open a unique file in @a dirpath, and write @a nbytes from @a buf to
    01902  * the file before flushing it to disk and closing it.  Return the name
    01903  * of the newly created file in @a *tmp_path, allocated in @a pool.
    01904  *
    01905  * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
    01906  * (Note that when using the system-provided temp directory, it may not
    01907  * be possible to atomically rename the resulting file due to cross-device
    01908  * issues.)
    01909  *
    01910  * The file will be deleted according to @a delete_when.
    01911  *
    01912  * @since New in 1.6.
    01913  */
    01914 svn_error_t *
    01915 svn_io_write_unique(const char **tmp_path,
    01916                     const char *dirpath,
    01917                     const void *buf,
    01918                     apr_size_t nbytes,
    01919                     svn_io_file_del_t delete_when,
    01920                     apr_pool_t *pool);
    01921
    01922 /** Wrapper for apr_file_trunc().
    01923   * @since New in 1.6. */
    01924 svn_error_t *
    01925 svn_io_file_trunc(apr_file_t *file,
    01926                   apr_off_t offset,
    01927                   apr_pool_t *pool);
    01928
    01929
    01930 /** Wrapper for apr_stat().  @a fname is utf8-encoded. */
    01931 svn_error_t *
    01932 svn_io_stat(apr_finfo_t *finfo,
    01933             const char *fname,
    01934             apr_int32_t wanted,
    01935             apr_pool_t *pool);
    01936
    01937
    01938 /** Rename and/or move the node (not necessarily a regular file) at
    01939  * @a from_path to a new path @a to_path within the same filesystem.
    01940  * In some cases, an existing node at @a to_path will be overwritten.
    01941  *
    01942  * A wrapper for apr_file_rename().  @a from_path and @a to_path are
    01943  * utf8-encoded.
    01944  */
    01945 svn_error_t *
    01946 svn_io_file_rename(const char *from_path,
    01947                    const char *to_path,
    01948                    apr_pool_t *pool);
    01949
    01950
    01951 /** Move the file from @a from_path to @a to_path, even across device
    01952  * boundaries. Overwrite @a to_path if it exists.
    01953  *
    01954  * @note This function is different from svn_io_file_rename in that the
    01955  * latter fails in the 'across device boundaries' case.
    01956  *
    01957  * @since New in 1.3.
    01958  */
    01959 svn_error_t *
    01960 svn_io_file_move(const char *from_path,
    01961                  const char *to_path,
    01962                  apr_pool_t *pool);
    01963
    01964
    01965 /** Wrapper for apr_dir_make().  @a path is utf8-encoded. */
    01966 svn_error_t *
    01967 svn_io_dir_make(const char *path,
    01968                 apr_fileperms_t perm,
    01969                 apr_pool_t *pool);
    01970
    01971 /** Same as svn_io_dir_make(), but sets the hidden attribute on the
    01972     directory on systems that support it. */
    01973 svn_error_t *
    01974 svn_io_dir_make_hidden(const char *path,
    01975                        apr_fileperms_t perm,
    01976                        apr_pool_t *pool);
    01977
    01978 /**
    01979  * Same as svn_io_dir_make(), but attempts to set the sgid on the
    01980  * directory on systems that support it.  Does not return an error if
    01981  * the attempt to set the sgid bit fails.  On Unix filesystems,
    01982  * setting the sgid bit on a directory ensures that files and
    01983  * subdirectories created within inherit group ownership from the
    01984  * parent instead of from the primary gid.
    01985  *
    01986  * @since New in 1.1.
    01987  */
    01988 svn_error_t *
    01989 svn_io_dir_make_sgid(const char *path,
    01990                      apr_fileperms_t perm,
    01991                      apr_pool_t *pool);
    01992
    01993 /** Wrapper for apr_dir_open().  @a dirname is utf8-encoded. */
    01994 svn_error_t *
    01995 svn_io_dir_open(apr_dir_t **new_dir,
    01996                 const char *dirname,
    01997                 apr_pool_t *pool);
    01998
    01999 /** Wrapper for apr_dir_close().
    02000  *
    02001  * @since New in 1.7.
    02002  */
    02003 svn_error_t *
    02004 svn_io_dir_close(apr_dir_t *thedir);
    02005
    02006 /** Wrapper for apr_dir_remove().  @a dirname is utf8-encoded.
    02007  * @note This function has this name to avoid confusion with
    02008  * svn_io_remove_dir2(), which is recursive.
    02009  */
    02010 svn_error_t *
    02011 svn_io_dir_remove_nonrecursive(const char *dirname,
    02012                                apr_pool_t *pool);
    02013
    02014
    02015 /** Wrapper for apr_dir_read().  Ensures that @a finfo->name is
    02016  * utf8-encoded, which means allocating @a finfo->name in @a pool,
    02017  * which may or may not be the same as @a finfo's pool.  Use @a pool
    02018  * for error allocation as well.
    02019  */
    02020 svn_error_t *
    02021 svn_io_dir_read(apr_finfo_t *finfo,
    02022                 apr_int32_t wanted,
    02023                 apr_dir_t *thedir,
    02024                 apr_pool_t *pool);
    02025
    02026 /** Wrapper for apr_file_name_get().  @a *filename is utf8-encoded.
    02027  *
    02028  * @note The file name may be NULL.
    02029  *
    02030  * @since New in 1.7. */
    02031 svn_error_t *
    02032 svn_io_file_name_get(const char **filename,
    02033                      apr_file_t *file,
    02034                      apr_pool_t *pool);
    02035
    02036
    02037
    02038 /** Version/format files.
    02039  *
    02040  * @defgroup svn_io_format_files Version/format files
    02041  * @{
    02042  */
    02043
    02044 /** Set @a *version to the integer that starts the file at @a path.  If the
    02045  * file does not begin with a series of digits followed by a newline,
    02046  * return the error #SVN_ERR_BAD_VERSION_FILE_FORMAT.  Use @a pool for
    02047  * all allocations.
    02048  */
    02049 svn_error_t *
    02050 svn_io_read_version_file(int *version,
    02051                          const char *path,
    02052                          apr_pool_t *pool);
    02053
    02054 /** Create (or overwrite) the file at @a path with new contents,
    02055  * formatted as a non-negative integer @a version followed by a single
    02056  * newline.  On successful completion the file will be read-only.  Use
    02057  * @a pool for all allocations.
    02058  */
    02059 svn_error_t *
    02060 svn_io_write_version_file(const char *path,
    02061                           int version,
    02062                           apr_pool_t *pool);
    02063
    02064 /** @} */
    02065
    02066 #ifdef __cplusplus
    02067 }
    02068 #endif /* __cplusplus */
    02069
    02070 #endif /* SVN_IO_H */

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines