svn_io.h

linux subdivision ying gai ke yi le ba

/**
 * @copyright
 * ====================================================================
 * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at http://subversion.tigris.org/license-1.html.
 * If newer versions of this license are posted there, you may use a
 * newer version instead, at your option.
 *
 * This software consists of voluntary contributions made by many
 * individuals.  For exact contribution history, see the revision
 * history and logs, available at http://subversion.tigris.org/.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_io.h
 * @brief general Subversion I/O definitions
 */

/* ==================================================================== */


#ifndef SVN_IO_H
#define SVN_IO_H

#include <apr.h>
#include <apr_pools.h>
#include <apr_file_io.h>
#include <apr_thread_proc.h>

#include "svn_types.h"
#include "svn_error.h"
#include "svn_string.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */



/** Determine the @a kind of @a path.
 *
 * If utf8-encoded @a path exists, set @a *kind to the appropriate kind,
 * else set it to @c svn_node_unknown. 
 *
 * If @a path is a file, @a *kind is set to @c svn_node_file.
 *
 * If @a path is a directory, @a *kind is set to @c svn_node_dir.
 *
 * If @a path does not exist in its final component, @a *kind is set to
 * @c svn_node_none.  
 *
 * If intermediate directories on the way to @a path don't exist, an
 * error is returned, and @a *kind's value is undefined.
 */
svn_error_t *svn_io_check_path (const char *path,
                                svn_node_kind_t *kind,
                                apr_pool_t *pool);

/**
 * @since New in 1.1.
 *
 * Like svn_io_check_path(), but also set *is_special to @c TRUE if
 * the path is not a normal file.
 */
svn_error_t *svn_io_check_special_path (const char *path,
                                        svn_node_kind_t *kind,
                                        svn_boolean_t *is_special,
                                        apr_pool_t *pool);

/** Like svn_io_check_path(), but resolve symlinks.  This returns the
    same varieties of @a kind as svn_io_check_path(). */ 
svn_error_t *svn_io_check_resolved_path (const char *path,
                                         svn_node_kind_t *kind,
                                         apr_pool_t *pool);


/** Open a new file (for writing) with a unique name based on utf-8
 * encoded @a path, in the same directory as @a path.  The file handle is
 * returned in @a *f, and the name, which ends with @a suffix, is returned
 * in @a *unique_name_p, also utf8-encoded.  If @a delete_on_close is set,
 * then the @c APR_DELONCLOSE flag will be used when opening the file. The
 * @c APR_BUFFERED flag will always be used.
 *
 * @a suffix may not be null.
 *
 * The first attempt will just append @a suffix.  If the result is not
 * a unique name, then subsequent attempts will append a dot,
 * followed by an iteration number ("2", then "3", and so on),
 * followed by the suffix.  For example, if @a path is
 *
 *    tests/t1/A/D/G/pi
 *
 * then successive calls to
 *
 *    @c svn_io_open_unique_file(&f, &unique_name, @a path, ".tmp", pool) 
 *
 * will open
 *
 *    tests/t1/A/D/G/pi.tmp
 *    tests/t1/A/D/G/pi.2.tmp
 *    tests/t1/A/D/G/pi.3.tmp
 *    tests/t1/A/D/G/pi.4.tmp
 *    tests/t1/A/D/G/pi.5.tmp
 *    ...
 *
 * @a *unique_name_p will never be exactly the same as @a path, even
 * if @a path does not exist.
 * 
 * It doesn't matter if @a path is a file or directory, the unique name will
 * be in @a path's parent either way.
 *
 * Allocate @a *f and @a *unique_name_p in @a pool.
 *
 * If no unique name can be found, @c SVN_ERR_IO_UNIQUE_NAMES_EXHAUSTED is
 * the error returned.
 *
 * Claim of Historical Inevitability: this function was written
 * because 
 *
 *    - @c tmpnam() is not thread-safe.
 *    - @c tempname() tries standard system tmp areas first.
 */
svn_error_t *svn_io_open_unique_file (apr_file_t **f,
                                      const char **unique_name_p,
                                      const char *path,
                                      const char *suffix,
                                      svn_boolean_t delete_on_close,
                                      apr_pool_t *pool);

/**
 * @since New in 1.1.
 *
 * Like svn_io_open_unique_file, except that instead of creating a
 * file, a symlink is generated that references the path @a dest.
 */
svn_error_t *svn_io_create_unique_link (const char **unique_name_p,
                                        const char *path,
                                        const char *dest,
                                        const char *suffix,
                                        apr_pool_t *pool);


/**
 * @since New in 1.1.
 *
 * Set @a dest to the path that the symlink at @a path references.
 * Allocate the string from @a pool.
 */
svn_error_t *svn_io_read_link (svn_string_t **dest,
                               const char *path,
                               apr_pool_t *pool);


/** Set @a dir to a directory path (allocated in @a pool) deemed
 * usable for the creation of temporary files and subdirectories.
 */
svn_error_t *svn_io_temp_dir (const char **dir,
                              apr_pool_t *pool);


/** Copy @a src to @a dst atomically.  Overwrite @a dst if it exists, else
 * create it.  Both @a src and @a dst are utf8-encoded filenames.  If
 * @a copy_perms is true, set @a dst's permissions to match those of @a src.
 */
svn_error_t *svn_io_copy_file (const char *src,
                               const char *dst,
                               svn_boolean_t copy_perms,
                               apr_pool_t *pool);

/** 
 * @since New in 1.1.
 *
 * Copy symbolic link @a src to @a dst atomically.  Overwrite @a dst
 * if it exists, else create it.  Both @a src and @a dst are
 * utf8-encoded filenames.  After copying, the @a dst link will point
 * to the same thing @a src does.
 */
svn_error_t *svn_io_copy_link (const char *src,
                               const char *dst,
                               apr_pool_t *pool);


/** Recursively copy directory @a src into @a dst_parent, as a new entry named
 * @a dst_basename.  If @a dst_basename already exists in @a dst_parent, 
 * return error.  @a copy_perms will be passed through to @c svn_io_copy_file 
 * when any files are copied.  @a src, @a dst_parent, and @a dst_basename are 
 * all utf8-encoded.
 *
 * If @a cancel_func is non-null, invoke it with @a cancel_baton at
 * various points during the operation.  If it returns any error
 * (typically @c SVN_ERR_CANCELLED), return that error immediately.
 */ 
svn_error_t *svn_io_copy_dir_recursively (const char *src,
                                          const char *dst_parent,
                                          const char *dst_basename,
                                          svn_boolean_t copy_perms,
                                          svn_cancel_func_t cancel_func,
                                          void *cancel_baton,
                                          apr_pool_t *pool);



/** Create directory @a path on the file system, creating intermediate
 * directories as required, like <tt>mkdir -p</tt>.  Report no error if @a 
 * path already exists.  @a path is utf8-encoded.
 *
 * This is essentially a wrapper for @c apr_dir_make_recursive(), passing
 * @c APR_OS_DEFAULT as the permissions.
 */
svn_error_t *svn_io_make_dir_recursively (const char *path, apr_pool_t *pool);


/** Set @a *is_empty_p to @c TRUE if directory @a path is empty, else to 
 * @c FALSE if it is not empty.  @a path must be a directory, and is
 * utf8-encoded.  Use @a pool for temporary allocation.
 */
svn_error_t *
svn_io_dir_empty (svn_boolean_t *is_empty_p,
                  const char *path,
                  apr_pool_t *pool);


/** Append @a src to @a dst.  @a dst will be appended to if it exists, else it
 * will be created.  Both @a src and @a dst are utf8-encoded.
 */
svn_error_t *svn_io_append_file (const char *src,
                                 const char *dst,
                                 apr_pool_t *pool);


/** Make a file as read-only as the operating system allows.
 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is
 * @c TRUE, don't fail if the target file doesn't exist.
 */
svn_error_t *svn_io_set_file_read_only (const char *path,
                                        svn_boolean_t ignore_enoent,
                                        apr_pool_t *pool);


/** Make a file as writable as the operating system allows.
 * @a path is the utf8-encoded path to the file.  If @a ignore_enoent is
 * @c TRUE, don't fail if the target file doesn't exist.
 * @warning On Unix this function will do the equivlanet of chmod a+w path.
 * If this is not what you want you should not use this function, but rather
 * use apr_file_perms_set().
 */
svn_error_t *svn_io_set_file_read_write (const char *path,
                                         svn_boolean_t ignore_enoent,
                                         apr_pool_t *pool);

/** Toggle a file's "executability".
 *
 * When making the file executable on operating systems with unix style
 * permissions, never add an execute permission where there is not
 * already a read permission: that is, only make the file executable
 * for the user, group or world if the corresponding read permission
 * is already set for user, group or world.
 *
 * When making the file non-executable on operating systems with unix style
 * permissions, remove all execute permissions.
 *
 * On other operating systems, toggle the file's "executability" as much as
 * the operating system allows.
 *
 * @a path is the utf8-encoded path to the file.  If @a executable
 * is @c TRUE, then make the file executable.  If @c FALSE, make in
 * non-executable.  If @a ignore_enoent is @c TRUE, don't fail if the target
 * file doesn't exist.
 */
svn_error_t *svn_io_set_file_executable (const char *path,
                                         svn_boolean_t executable,
                                         svn_boolean_t ignore_enoent,
                                         apr_pool_t *pool);

/** Determine whether a file is executable by the current user.  
 * Set @a *executable to @c TRUE if the file @a path is executable by the 
 * current user, otherwise set it to @c FALSE.  
 * 
 * On Windows and on platforms without userids, always returns @c FALSE.
 */
svn_error_t *svn_io_is_file_executable(svn_boolean_t *executable, 
                                       const char *path, 
                                       apr_pool_t *pool);


/** Read a line from @a file into @a buf, but not exceeding @a *limit bytes.
 * Does not include newline, instead '\\0' is put there.
 * Length (as in strlen) is returned in @a *limit.
 * @a buf should be pre-allocated.
 * @a file should be already opened. 
 *
 * When the file is out of lines, @c APR_EOF will be returned.