svn_io.h

linux subdivision ying gai ke yi le ba

 *
 * Note:  the `.' and `..' directories normally returned by
 * @c apr_dir_read are NOT returned in the hash.
 */
svn_error_t *svn_io_get_dirents (apr_hash_t **dirents,
                                 const char *path,
                                 apr_pool_t *pool);


/** Callback function type for @c svn_io_dir_walk  */
typedef svn_error_t * (*svn_io_walk_func_t) (void *baton,
                                             const char *path,
                                             const apr_finfo_t *finfo,
                                             apr_pool_t *pool);

/** This function will recursively walk over the files and directories
 * rooted at @a dirname, a utf8-encoded path. For each file or directory,
 * @a walk_func is invoked, passing in the @a walk_baton, the utf8-encoded
 * full path to the entry, an @c apr_finfo_t structure, and a temporary
 * pool for allocations.  For any directory, @a walk_func will be invoked
 * on the directory itself before being invoked on any subdirectories or
 * files within the directory.
 *
 * The set of information passed to @a walk_func is specified by @a wanted,
 * and the items specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME.
 *
 * All allocations will be performed in @a pool.
 */
svn_error_t *svn_io_dir_walk (const char *dirname,
                              apr_int32_t wanted,
                              svn_io_walk_func_t walk_func,
                              void *walk_baton,
                              apr_pool_t *pool);

/** Invoke @a cmd with @a args, using utf8-encoded @a path as working 
 * directory.  Connect @a cmd's stdin, stdout, and stderr to @a infile, 
 * @a outfile, and @a errfile, except where they are null.
 *
 * If set, @a exitcode will contain the exit code of the process upon return,
 * and @a exitwhy will indicate why the process terminated. If @a exitwhy is 
 * not set and the exit reason is not @c APR_PROC_CHECK_EXIT(), or if 
 * @a exitcode is not set and the exit code is non-zero, then an 
 * @c SVN_ERR_EXTERNAL_PROGRAM error will be returned.
 *
 * @a args is a list of utf8-encoded (<tt>const char *</tt>)'s, terminated by
 * @c NULL.  @c ARGS[0] is the name of the program, though it need not be
 * the same as @a cmd.
 *
 * @a inherit sets whether the invoked program shall inherit its environment or
 * run "clean".
 */
svn_error_t *svn_io_run_cmd (const char *path,
                             const char *cmd,
                             const char *const *args,
                             int *exitcode,
                             apr_exit_why_e *exitwhy,
                             svn_boolean_t inherit,
                             apr_file_t *infile,
                             apr_file_t *outfile,
                             apr_file_t *errfile,
                             apr_pool_t *pool);

/** Invoke @c the configured diff program, with @a user_args (an array
 * of utf8-encoded @a num_user_args arguments), if they are specified,
 * or "-u" if they are not.
 *
 * Diff runs in utf8-encoded @a dir, and its exit status is stored in
 * @a exitcode, if it is not @c NULL.  
 *
 * If @a label1 and/or @a label2 are not null they will be passed to the diff
 * process as the arguments of "-L" options.  @a label1 and @a label2 are also 
 * in utf8, and will be converted to native charset along with the other args.
 *
 * @a from is the first file passed to diff, and @a to is the second.  The
 * stdout of diff will be sent to @a outfile, and the stderr to @a errfile.
 *
 * @a diff_cmd must be non-null.
 *
 * Do all allocation in @a pool. 
 */
svn_error_t *svn_io_run_diff (const char *dir,
                              const char *const *user_args,
                              int num_user_args,
                              const char *label1,
                              const char *label2,
                              const char *from,
                              const char *to,
                              int *exitcode,
                              apr_file_t *outfile,
                              apr_file_t *errfile,
                              const char *diff_cmd,
                              apr_pool_t *pool);


/** Invoke @c the configured diff3 program, in utf8-encoded @a dir
 * like this:
 *
 *          diff3 -Em @a mine @a older @a yours > @a merged
 *
 * (See the diff3 documentation for details.)
 *
 * @a mine, @a older, and @a yours are utf8-encoded paths, relative to @a dir, 
 * to three files that already exist.  @a merged is an open file handle, and
 * is left open after the merge result is written to it. (@a merged
 * should *not* be the same file as @a mine, or nondeterministic things
 * may happen!)
 *
 * @a mine_label, @a older_label, @a yours_label are utf8-encoded label
 * parameters for diff3's -L option.  Any of them may be @c NULL, in
 * which case the corresponding @a mine, @a older, or @a yours parameter is
 * used instead.
 *
 * Set @a *exitcode to diff3's exit status.  If @a *exitcode is anything
 * other than 0 or 1, then return @c SVN_ERR_EXTERNAL_PROGRAM.  (Note the
 * following from the diff3 info pages: "An exit status of 0 means
 * `diff3' was successful, 1 means some conflicts were found, and 2
 * means trouble.") 
 *
 * @a diff3_cmd must be non-null.
 *
 * Do all allocation in @a pool. 
 */
svn_error_t *svn_io_run_diff3 (const char *dir,
                               const char *mine,
                               const char *older,
                               const char *yours,
                               const char *mine_label,
                               const char *older_label,
                               const char *yours_label,
                               apr_file_t *merged,
                               int *exitcode,
                               const char *diff3_cmd,
                               apr_pool_t *pool);


/** Examine utf8-encoded @a file to determine if it can be described by a
 * known (as in, known by this function) Multipurpose Internet Mail
 * Extension (MIME) type.  If so, set @a mimetype to a character string
 * describing the MIME type, else set it to @c NULL.  Use @a pool for any
 * necessary allocations.
 */
svn_error_t *svn_io_detect_mimetype (const char **mimetype,
                                     const char *file,
                                     apr_pool_t *pool);
                                      

/** Wrapper for @c apr_file_open(), which see.  @a fname is utf8-encoded. */
svn_error_t *
svn_io_file_open (apr_file_t **new_file, const char *fname,
                  apr_int32_t flag, apr_fileperms_t perm,
                  apr_pool_t *pool);


/** Wrapper for @c apr_file_close(), which see. */
svn_error_t *
svn_io_file_close (apr_file_t *file, apr_pool_t *pool);


/** Wrapper for @c apr_file_getc(), which see. */
svn_error_t *
svn_io_file_getc (char *ch, apr_file_t *file, apr_pool_t *pool);


/** Wrapper for @c apr_file_info_get(), which see. */
svn_error_t *
svn_io_file_info_get (apr_finfo_t *finfo, apr_int32_t wanted, 
                      apr_file_t *file, apr_pool_t *pool);


/** Wrapper for @c apr_file_read(), which see. */
svn_error_t *
svn_io_file_read (apr_file_t *file, void *buf, 
                  apr_size_t *nbytes, apr_pool_t *pool);


/** Wrapper for @c apr_file_read_full(), which see. */
svn_error_t *
svn_io_file_read_full (apr_file_t *file, void *buf, 
                       apr_size_t nbytes, apr_size_t *bytes_read,
                       apr_pool_t *pool);


/** Wrapper for @c apr_file_seek(), which see. */
svn_error_t *
svn_io_file_seek (apr_file_t *file, apr_seek_where_t where, 
                  apr_off_t *offset, apr_pool_t *pool);


/** Wrapper for @c apr_file_write(), which see. */
svn_error_t *
svn_io_file_write (apr_file_t *file, const void *buf, 
                   apr_size_t *nbytes, apr_pool_t *pool);


/** Wrapper for @c apr_file_write_full(), which see. */
svn_error_t *
svn_io_file_write_full (apr_file_t *file, const void *buf, 
                        apr_size_t nbytes, apr_size_t *bytes_written,
                        apr_pool_t *pool);


/** Wrapper for @c apr_stat(), which see.  @a fname is utf8-encoded. */
svn_error_t *
svn_io_stat (apr_finfo_t *finfo, const char *fname,
             apr_int32_t wanted, apr_pool_t *pool);


/** Wrapper for @c apr_file_rename(), which see.  @a from_path and @a to_path
 * are utf8-encoded.
 */
svn_error_t *
svn_io_file_rename (const char *from_path, const char *to_path,
                    apr_pool_t *pool);


/** Wrapper for @c apr_dir_make(), which see.  @a path is utf8-encoded. */
svn_error_t *
svn_io_dir_make (const char *path, apr_fileperms_t perm, apr_pool_t *pool);

/** Same as svn_io_dir_make, but sets the hidden attribute on the
    directory on systems that support it. */
svn_error_t *
svn_io_dir_make_hidden (const char *path, apr_fileperms_t perm,
                        apr_pool_t *pool);

/**
 * @since New in 1.1.
 *
 * Same as svn_io_dir_make, but attempts to set the sgid on the
 * directory on systems that support it.  Does not return an error if
 * the attempt to set the sgid bit fails.  On Unix filesystems,
 * setting the sgid bit on a directory ensures that files and
 * subdirectories created within inherit group ownership from the
 * parent instead of from the primary gid. */
svn_error_t *
svn_io_dir_make_sgid (const char *path, apr_fileperms_t perm,
                      apr_pool_t *pool);

/** Wrapper for @c apr_dir_open(), which see.  @a dirname is utf8-encoded. */
svn_error_t *
svn_io_dir_open (apr_dir_t **new_dir, const char *dirname, apr_pool_t *pool);


/** Wrapper for @c apr_dir_remove(), which see.  @a dirname is utf8-encoded.
 * Note: this function has this name to avoid confusion with
 * @c svn_io_remove_dir, which is recursive.
 */
svn_error_t *
svn_io_dir_remove_nonrecursive (const char *dirname, apr_pool_t *pool);


/** Wrapper for @c apr_dir_read, which see.  Ensures that @a finfo->name is
 * utf8-encoded, which means allocating @a finfo->name in @a pool, which may
 * or may not be the same as @a finfo's pool.  Use @a pool for error allocation
 * as well.
 */
svn_error_t *
svn_io_dir_read (apr_finfo_t *finfo,
                 apr_int32_t wanted,
                 apr_dir_t *thedir,
                 apr_pool_t *pool);



/** Version/format files. 
 *
 * @defgroup svn_io_format_files version/format files
 * @{
 */

/** Set @a *version to the integer that starts the file at @a path.  If the
 * file does not begin with a series of digits followed by a newline,
 * return the error @c SVN_ERR_BAD_VERSION_FILE_FORMAT.  Use @a pool for
 * all allocations.
 */
svn_error_t *
svn_io_read_version_file (int *version, const char *path, apr_pool_t *pool);

/** Create (or overwrite) the file at @a path with new contents,
 * formatted as a non-negative integer @a version followed by a single
 * newline.  On successful completion the file will be read-only.  Use
 * @a pool for all allocations.
 */
svn_error_t *
svn_io_write_version_file (const char *path, int version, apr_pool_t *pool);

/** @} */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* SVN_IO_H */