3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief General file I/O for Subversion
27 /* ==================================================================== */
34 #include <apr_pools.h>
37 #include <apr_tables.h>
38 #include <apr_file_io.h>
39 #include <apr_file_info.h>
40 #include <apr_thread_proc.h> /* for apr_proc_t, apr_exit_why_e */
42 #include "svn_types.h"
43 #include "svn_string.h"
44 #include "svn_checksum.h"
48 #endif /* __cplusplus */
52 /** Used as an argument when creating temporary files to indicate
53 * when a file should be removed.
57 * Not specifying any of these means no removal at all. */
58 typedef enum svn_io_file_del_t
60 /** No deletion ever */
61 svn_io_file_del_none = 0,
62 /** Remove when the file is closed */
63 svn_io_file_del_on_close,
64 /** Remove when the associated pool is cleared */
65 svn_io_file_del_on_pool_cleanup
68 /** A set of directory entry data elements as returned by svn_io_get_dirents
70 * Note that the first two fields are exactly identical to svn_io_dirent_t
71 * to allow returning a svn_io_dirent2_t as a svn_io_dirent_t.
73 * Use svn_io_dirent2_create() to create new svn_dirent2_t instances or
74 * svn_io_dirent2_dup() to duplicate an existing instance.
78 typedef struct svn_io_dirent2_t {
79 /* New fields must be added at the end to preserve binary compatibility */
81 /** The kind of this entry. */
84 /** If @c kind is #svn_node_file, whether this entry is a special file;
87 * @see svn_io_check_special_path().
89 svn_boolean_t special;
91 /** The filesize of this entry or undefined for a directory */
92 svn_filesize_t filesize;
94 /** The time the file was last modified */
97 /* Don't forget to update svn_io_dirent2_dup() when adding new fields */
101 /** Creates a new #svn_io_dirent2_t structure
106 svn_io_dirent2_create(apr_pool_t *result_pool);
108 /** Duplicates a @c svn_io_dirent2_t structure into @a result_pool.
113 svn_io_dirent2_dup(const svn_io_dirent2_t *item,
114 apr_pool_t *result_pool);
116 /** Represents the kind and special status of a directory entry.
118 * Note that the first two fields are exactly identical to svn_io_dirent2_t
119 * to allow returning a svn_io_dirent2_t as a svn_io_dirent_t.
123 typedef struct svn_io_dirent_t {
124 /** The kind of this entry. */
125 svn_node_kind_t kind;
126 /** If @c kind is #svn_node_file, whether this entry is a special file;
129 * @see svn_io_check_special_path().
131 svn_boolean_t special;
134 /** Determine the @a kind of @a path. @a path should be UTF-8 encoded.
136 * If @a path is a file, set @a *kind to #svn_node_file.
138 * If @a path is a directory, set @a *kind to #svn_node_dir.
140 * If @a path does not exist, set @a *kind to #svn_node_none.
142 * If @a path exists but is none of the above, set @a *kind to
145 * If @a path is not a valid pathname, set @a *kind to #svn_node_none. If
146 * unable to determine @a path's kind for any other reason, return an error,
147 * with @a *kind's value undefined.
149 * Use @a pool for temporary allocations.
151 * @see svn_node_kind_t
154 svn_io_check_path(const char *path,
155 svn_node_kind_t *kind,
159 * Like svn_io_check_path(), but also set *is_special to @c TRUE if
160 * the path is not a normal file.
165 svn_io_check_special_path(const char *path,
166 svn_node_kind_t *kind,
167 svn_boolean_t *is_special,
170 /** Like svn_io_check_path(), but resolve symlinks. This returns the
171 same varieties of @a kind as svn_io_check_path(). */
173 svn_io_check_resolved_path(const char *path,
174 svn_node_kind_t *kind,
178 /** Open a new file (for reading and writing) with a unique name based on
179 * utf-8 encoded @a filename, in the directory @a dirpath. The file handle is
180 * returned in @a *file, and the name, which ends with @a suffix, is returned
181 * in @a *unique_name, also utf8-encoded. Either @a file or @a unique_name
182 * may be @c NULL. If @a file is @c NULL, the file will be created but not
185 * The file will be deleted according to @a delete_when. If that is
186 * #svn_io_file_del_on_pool_cleanup, it refers to @a result_pool.
188 * The @c APR_BUFFERED flag will always be used when opening the file.
190 * The first attempt will just append @a suffix. If the result is not
191 * a unique name, then subsequent attempts will append a dot,
192 * followed by an iteration number ("2", then "3", and so on),
193 * followed by the suffix. For example, successive calls to
195 * svn_io_open_uniquely_named(&f, &u, "tests/t1/A/D/G", "pi", ".tmp", ...)
199 * tests/t1/A/D/G/pi.tmp
200 * tests/t1/A/D/G/pi.2.tmp
201 * tests/t1/A/D/G/pi.3.tmp
202 * tests/t1/A/D/G/pi.4.tmp
203 * tests/t1/A/D/G/pi.5.tmp
206 * Assuming @a suffix is non-empty, @a *unique_name will never be exactly
207 * the same as @a filename, even if @a filename does not exist.
209 * If @a dirpath is NULL, then the directory returned by svn_io_temp_dir()
212 * If @a filename is NULL, then "tempfile" will be used.
214 * If @a suffix is NULL, then ".tmp" will be used.
216 * Allocates @a *file and @a *unique_name in @a result_pool. All
217 * intermediate allocations will be performed in @a scratch_pool.
219 * If no unique name can be found, #SVN_ERR_IO_UNIQUE_NAMES_EXHAUSTED is
220 * the error returned.
222 * Claim of Historical Inevitability: this function was written
225 * - tmpnam() is not thread-safe.
226 * - tempname() tries standard system tmp areas first.
231 svn_io_open_uniquely_named(apr_file_t **file,
232 const char **unique_name,
234 const char *filename,
236 svn_io_file_del_t delete_when,
237 apr_pool_t *result_pool,
238 apr_pool_t *scratch_pool);
241 /** Create a writable file, with an arbitrary and unique name, in the
242 * directory @a dirpath. Set @a *temp_path to its full path, and set
243 * @a *file to the file handle, both allocated from @a result_pool. Either
244 * @a file or @a temp_path may be @c NULL. If @a file is @c NULL, the file
245 * will be created but not open.
247 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
248 * (Note that when using the system-provided temp directory, it may not
249 * be possible to atomically rename the resulting file due to cross-device
252 * The file will be deleted according to @a delete_when. If that is
253 * #svn_io_file_del_on_pool_cleanup, it refers to @a result_pool. If it
254 * is #svn_io_file_del_on_close and @a file is @c NULL, the file will be
255 * deleted before this function returns.
257 * When passing @c svn_io_file_del_none please don't forget to eventually
258 * remove the temporary file to avoid filling up the system temp directory.
259 * It is often appropriate to bind the lifetime of the temporary file to
260 * the lifetime of a pool by using @c svn_io_file_del_on_pool_cleanup.
262 * Temporary allocations will be performed in @a scratch_pool.
265 * @see svn_stream_open_unique()
268 svn_io_open_unique_file3(apr_file_t **file,
269 const char **temp_path,
271 svn_io_file_del_t delete_when,
272 apr_pool_t *result_pool,
273 apr_pool_t *scratch_pool);
276 /** Like svn_io_open_uniquely_named(), but takes a joined dirpath and
277 * filename, and a single pool.
281 * @deprecated Provided for backward compatibility with the 1.5 API
285 svn_io_open_unique_file2(apr_file_t **f,
286 const char **unique_name_p,
289 svn_io_file_del_t delete_when,
292 /** Like svn_io_open_unique_file2, but can't delete on pool cleanup.
294 * @deprecated Provided for backward compatibility with the 1.3 API
296 * @note In 1.4 the API was extended to require either @a f or
297 * @a unique_name_p (the other can be NULL). Before that, both were
302 svn_io_open_unique_file(apr_file_t **f,
303 const char **unique_name_p,
306 svn_boolean_t delete_on_close,
311 * Like svn_io_open_unique_file(), except that instead of creating a
312 * file, a symlink is generated that references the path @a dest.
317 svn_io_create_unique_link(const char **unique_name_p,
325 * Set @a *dest to the path that the symlink at @a path references.
326 * Allocate the string from @a pool.
331 svn_io_read_link(svn_string_t **dest,
336 /** Set @a *dir to a directory path (allocated in @a pool) deemed
337 * usable for the creation of temporary files and subdirectories.
340 svn_io_temp_dir(const char **dir,
344 /** Copy @a src to @a dst atomically, in a "byte-for-byte" manner.
345 * Overwrite @a dst if it exists, else create it. Both @a src and @a dst
346 * are utf8-encoded filenames. If @a copy_perms is TRUE, set @a dst's
347 * permissions to match those of @a src.
350 svn_io_copy_file(const char *src,
352 svn_boolean_t copy_perms,
356 /** Copy permission flags from @a src onto the file at @a dst. Both
357 * filenames are utf8-encoded filenames.
362 svn_io_copy_perms(const char *src,
368 * Copy symbolic link @a src to @a dst atomically. Overwrite @a dst
369 * if it exists, else create it. Both @a src and @a dst are
370 * utf8-encoded filenames. After copying, the @a dst link will point
371 * to the same thing @a src does.
376 svn_io_copy_link(const char *src,
381 /** Recursively copy directory @a src into @a dst_parent, as a new entry named
382 * @a dst_basename. If @a dst_basename already exists in @a dst_parent,
383 * return error. @a copy_perms will be passed through to svn_io_copy_file()
384 * when any files are copied. @a src, @a dst_parent, and @a dst_basename are
387 * If @a cancel_func is non-NULL, invoke it with @a cancel_baton at
388 * various points during the operation. If it returns any error
389 * (typically #SVN_ERR_CANCELLED), return that error immediately.
392 svn_io_copy_dir_recursively(const char *src,
393 const char *dst_parent,
394 const char *dst_basename,
395 svn_boolean_t copy_perms,
396 svn_cancel_func_t cancel_func,
401 /** Create directory @a path on the file system, creating intermediate
402 * directories as required, like <tt>mkdir -p</tt>. Report no error if @a
403 * path already exists. @a path is utf8-encoded.
405 * This is essentially a wrapper for apr_dir_make_recursive(), passing
406 * @c APR_OS_DEFAULT as the permissions.
409 svn_io_make_dir_recursively(const char *path,
413 /** Set @a *is_empty_p to @c TRUE if directory @a path is empty, else to
414 * @c FALSE if it is not empty. @a path must be a directory, and is
415 * utf8-encoded. Use @a pool for temporary allocation.
418 svn_io_dir_empty(svn_boolean_t *is_empty_p,
423 /** Append @a src to @a dst. @a dst will be appended to if it exists, else it
424 * will be created. Both @a src and @a dst are utf8-encoded.
427 svn_io_append_file(const char *src,
432 /** Make a file as read-only as the operating system allows.
433 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is
434 * @c TRUE, don't fail if the target file doesn't exist.
436 * If @a path is a symlink, do nothing.
438 * @note If @a path is a directory, act on it as though it were a
439 * file, as described above, but note that you probably don't want to
440 * call this function on directories. We have left it effective on
441 * directories for compatibility reasons, but as its name implies, it
442 * should be used only for files.
445 svn_io_set_file_read_only(const char *path,
446 svn_boolean_t ignore_enoent,
450 /** Make a file as writable as the operating system allows.
451 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is
452 * @c TRUE, don't fail if the target file doesn't exist.
453 * @warning On Unix this function will do the equivalent of chmod a+w path.
454 * If this is not what you want you should not use this function, but rather
455 * use apr_file_perms_set().
457 * If @a path is a symlink, do nothing.
459 * @note If @a path is a directory, act on it as though it were a
460 * file, as described above, but note that you probably don't want to
461 * call this function on directories. We have left it effective on
462 * directories for compatibility reasons, but as its name implies, it
463 * should be used only for files.
466 svn_io_set_file_read_write(const char *path,
467 svn_boolean_t ignore_enoent,
471 /** Similar to svn_io_set_file_read_* functions.
472 * Change the read-write permissions of a file.
475 * When making @a path read-write on operating systems with unix style
476 * permissions, set the permissions on @a path to the permissions that
477 * are set when a new file is created (effectively honoring the user's
480 * When making the file read-only on operating systems with unix style
481 * permissions, remove all write permissions.
483 * On other operating systems, toggle the file's "writability" as much as
484 * the operating system allows.
486 * @a path is the utf8-encoded path to the file. If @a enable_write
487 * is @c TRUE, then make the file read-write. If @c FALSE, make it
488 * read-only. If @a ignore_enoent is @c TRUE, don't fail if the target
489 * file doesn't exist.
491 * @deprecated Provided for backward compatibility with the 1.3 API.
495 svn_io_set_file_read_write_carefully(const char *path,
496 svn_boolean_t enable_write,
497 svn_boolean_t ignore_enoent,
500 /** Set @a path's "executability" (but do nothing if it is a symlink).
502 * @a path is the utf8-encoded path to the file. If @a executable
503 * is @c TRUE, then make the file executable. If @c FALSE, make it
504 * non-executable. If @a ignore_enoent is @c TRUE, don't fail if the target
505 * file doesn't exist.
507 * When making the file executable on operating systems with unix style
508 * permissions, never add an execute permission where there is not
509 * already a read permission: that is, only make the file executable
510 * for the user, group or world if the corresponding read permission
511 * is already set for user, group or world.
513 * When making the file non-executable on operating systems with unix style
514 * permissions, remove all execute permissions.
516 * On other operating systems, toggle the file's "executability" as much as
517 * the operating system allows.
519 * @note If @a path is a directory, act on it as though it were a
520 * file, as described above, but note that you probably don't want to
521 * call this function on directories. We have left it effective on
522 * directories for compatibility reasons, but as its name implies, it
523 * should be used only for files.
526 svn_io_set_file_executable(const char *path,
527 svn_boolean_t executable,
528 svn_boolean_t ignore_enoent,
531 /** Determine whether a file is executable by the current user.
532 * Set @a *executable to @c TRUE if the file @a path is executable by the
533 * current user, otherwise set it to @c FALSE.
535 * On Windows and on platforms without userids, always returns @c FALSE.
538 svn_io_is_file_executable(svn_boolean_t *executable,
543 /** Read a line from @a file into @a buf, but not exceeding @a *limit bytes.
544 * Does not include newline, instead '\\0' is put there.
545 * Length (as in strlen) is returned in @a *limit.
546 * @a buf should be pre-allocated.
547 * @a file should be already opened.
549 * When the file is out of lines, @c APR_EOF will be returned.
552 svn_io_read_length_line(apr_file_t *file,
558 /** Set @a *apr_time to the time of last modification of the contents of the
559 * file @a path. @a path is utf8-encoded.
561 * @note This is the APR mtime which corresponds to the traditional mtime
562 * on Unix, and the last write time on Windows.
565 svn_io_file_affected_time(apr_time_t *apr_time,
569 /** Set the timestamp of file @a path to @a apr_time. @a path is
572 * @note This is the APR mtime which corresponds to the traditional mtime
573 * on Unix, and the last write time on Windows.
576 svn_io_set_file_affected_time(apr_time_t apr_time,
580 /** Sleep to ensure that any files modified after we exit have a different
581 * timestamp than the one we recorded. If @a path is not NULL, check if we
582 * can determine how long we should wait for a new timestamp on the filesystem
583 * containing @a path, an existing file or directory. If @a path is NULL or we
584 * can't determine the timestamp resolution, sleep until the next second.
586 * Use @a pool for any necessary allocations. @a pool can be null if @a path
589 * Errors while retrieving the timestamp resolution will result in sleeping
590 * to the next second, to keep the working copy stable in error conditions.
595 svn_io_sleep_for_timestamps(const char *path, apr_pool_t *pool);
597 /** Set @a *different_p to TRUE if @a file1 and @a file2 have different
598 * sizes, else set to FALSE. Both @a file1 and @a file2 are utf8-encoded.
600 * Setting @a *different_p to zero does not mean the files definitely
601 * have the same size, it merely means that the sizes are not
602 * definitely different. That is, if the size of one or both files
603 * cannot be determined, then the sizes are not known to be different,
604 * so @a *different_p is set to FALSE.
607 svn_io_filesizes_different_p(svn_boolean_t *different_p,
612 /** Set @a *different_p12 to non-zero if @a file1 and @a file2 have different
613 * sizes, else set to zero. Do the similar for @a *different_p23 with
614 * @a file2 and @a file3, and @a *different_p13 for @a file1 and @a file3.
615 * The filenames @a file1, @a file2 and @a file3 are utf8-encoded.
617 * Setting @a *different_p12 to zero does not mean the files definitely
618 * have the same size, it merely means that the sizes are not
619 * definitely different. That is, if the size of one or both files
620 * cannot be determined (due to stat() returning an error), then the sizes
621 * are not known to be different, so @a *different_p12 is set to 0.
626 svn_io_filesizes_three_different_p(svn_boolean_t *different_p12,
627 svn_boolean_t *different_p23,
628 svn_boolean_t *different_p13,
632 apr_pool_t *scratch_pool);
634 /** Return in @a *checksum the checksum of type @a kind of @a file
635 * Use @a pool for temporary allocations and to allocate @a *checksum.
640 svn_io_file_checksum2(svn_checksum_t **checksum,
642 svn_checksum_kind_t kind,
646 /** Put the md5 checksum of @a file into @a digest.
647 * @a digest points to @c APR_MD5_DIGESTSIZE bytes of storage.
648 * Use @a pool only for temporary allocations.
650 * @deprecated Provided for backward compatibility with the 1.5 API.
654 svn_io_file_checksum(unsigned char digest[],
659 /** Set @a *same to TRUE if @a file1 and @a file2 have the same
660 * contents, else set it to FALSE. Use @a pool for temporary allocations.
663 svn_io_files_contents_same_p(svn_boolean_t *same,
668 /** Set @a *same12 to TRUE if @a file1 and @a file2 have the same
669 * contents, else set it to FALSE. Do the similar for @a *same23
670 * with @a file2 and @a file3, and @a *same13 for @a file1 and @a
671 * file3. The filenames @a file1, @a file2 and @a file3 are
672 * utf8-encoded. Use @a scratch_pool for temporary allocations.
677 svn_io_files_contents_three_same_p(svn_boolean_t *same12,
678 svn_boolean_t *same23,
679 svn_boolean_t *same13,
683 apr_pool_t *scratch_pool);
685 /** Create a file at utf8-encoded path @a file with the contents given
686 * by the null-terminated string @a contents.
688 * @a file must not already exist. If an error occurs while writing or
689 * closing the file, attempt to delete the file before returning the error.
691 * Write the data in 'binary' mode (#APR_FOPEN_BINARY). If @a contents
692 * is @c NULL, create an empty file.
694 * Use @a pool for memory allocations.
697 svn_io_file_create(const char *file,
698 const char *contents,
701 /** Create a file at utf8-encoded path @a file with the contents given
702 * by @a contents of @a length bytes.
704 * @a file must not already exist. If an error occurs while writing or
705 * closing the file, attempt to delete the file before returning the error.
707 * Write the data in 'binary' mode (#APR_FOPEN_BINARY). If @a length is
708 * zero, create an empty file; in this case @a contents may be @c NULL.
710 * Use @a scratch_pool for temporary allocations.
715 svn_io_file_create_bytes(const char *file,
716 const void *contents,
718 apr_pool_t *scratch_pool);
720 /** Create an empty file at utf8-encoded path @a file.
722 * @a file must not already exist. If an error occurs while
723 * closing the file, attempt to delete the file before returning the error.
725 * Use @a scratch_pool for temporary allocations.
730 svn_io_file_create_empty(const char *file,
731 apr_pool_t *scratch_pool);
734 * Lock file at @a lock_file. If @a exclusive is TRUE,
735 * obtain exclusive lock, otherwise obtain shared lock.
736 * Lock will be automatically released when @a pool is cleared or destroyed.
737 * Use @a pool for memory allocations.
739 * @deprecated Provided for backward compatibility with the 1.0 API.
743 svn_io_file_lock(const char *lock_file,
744 svn_boolean_t exclusive,
748 * Lock file at @a lock_file. If @a exclusive is TRUE,
749 * obtain exclusive lock, otherwise obtain shared lock.
751 * If @a nonblocking is TRUE, do not wait for the lock if it
752 * is not available: throw an error instead.
754 * Lock will be automatically released when @a pool is cleared or destroyed.
755 * Use @a pool for memory allocations.
760 svn_io_file_lock2(const char *lock_file,
761 svn_boolean_t exclusive,
762 svn_boolean_t nonblocking,
766 * Lock the file @a lockfile_handle. If @a exclusive is TRUE,
767 * obtain exclusive lock, otherwise obtain shared lock.
769 * If @a nonblocking is TRUE, do not wait for the lock if it
770 * is not available: throw an error instead.
772 * Lock will be automatically released when @a pool is cleared or destroyed.
773 * You may also explicitly call svn_io_unlock_open_file().
774 * Use @a pool for memory allocations. @a pool must be the pool that
775 * @a lockfile_handle has been created in or one of its sub-pools.
780 svn_io_lock_open_file(apr_file_t *lockfile_handle,
781 svn_boolean_t exclusive,
782 svn_boolean_t nonblocking,
786 * Unlock the file @a lockfile_handle.
788 * Use @a pool for memory allocations. @a pool must be the pool that
789 * was passed to svn_io_lock_open_file().
794 svn_io_unlock_open_file(apr_file_t *lockfile_handle,
798 * Flush any unwritten data from @a file to disk. Use @a pool for
799 * memory allocations.
801 * @note This function uses advanced file control operations to flush buffers
802 * to disk that aren't always accessible and can be very expensive on systems
803 * that implement flushing on all IO layers, like Windows. Please avoid using
804 * this function in cases where the file should just work on any network
805 * filesystem. In many cases a normal svn_io_file_flush() will work just fine.
810 svn_io_file_flush_to_disk(apr_file_t *file,
813 /** Copy the file whose basename (or relative path) is @a file within
814 * directory @a src_path to the same basename (or relative path) within
815 * directory @a dest_path. Overwrite the destination file if it already
816 * exists. The destination directory (including any directory
817 * components in @a name) must already exist. Set the destination
818 * file's permissions to match those of the source. Use @a pool for
819 * memory allocations.
822 svn_io_dir_file_copy(const char *src_path,
823 const char *dest_path,
828 /** Generic byte-streams
830 * @defgroup svn_io_byte_streams Generic byte streams
834 /** An abstract stream of bytes--either incoming or outgoing or both.
836 * The creator of a stream sets functions to handle read and write.
837 * Both of these handlers accept a baton whose value is determined at
838 * stream creation time; this baton can point to a structure
839 * containing data associated with the stream. If a caller attempts
840 * to invoke a handler which has not been set, it will generate a
841 * runtime assertion failure. The creator can also set a handler for
842 * close requests so that it can flush buffered data or whatever;
843 * if a close handler is not specified, a close request on the stream
844 * will simply be ignored. Note that svn_stream_close() does not
845 * deallocate the memory used to allocate the stream structure; free
846 * the pool you created the stream in to free that memory.
848 * The read and write handlers accept length arguments via pointer.
849 * On entry to the handler, the pointed-to value should be the amount
850 * of data which can be read or the amount of data to write. When the
851 * handler returns, the value is reset to the amount of data actually
852 * read or written. The write and full read handler are obliged to
853 * complete a read or write to the maximum extent possible; thus, a
854 * short read with no associated error implies the end of the input
855 * stream, and a short write should never occur without an associated
856 * error. In Subversion 1.9 the stream api was extended to also support
857 * limited reads via the new svn_stream_read2() api.
859 * In Subversion 1.7 mark, seek and reset support was added as an optional
860 * feature of streams. If a stream implements resetting it allows reading
861 * the data again after a successful call to svn_stream_reset().
863 typedef struct svn_stream_t svn_stream_t;
867 /** Read handler function for a generic stream. @see svn_stream_t. */
868 typedef svn_error_t *(*svn_read_fn_t)(void *baton,
872 /** Skip data handler function for a generic stream. @see svn_stream_t
873 * and svn_stream_skip().
876 typedef svn_error_t *(*svn_stream_skip_fn_t)(void *baton,
879 /** Write handler function for a generic stream. @see svn_stream_t. */
880 typedef svn_error_t *(*svn_write_fn_t)(void *baton,
884 /** Close handler function for a generic stream. @see svn_stream_t. */
885 typedef svn_error_t *(*svn_close_fn_t)(void *baton);
887 /** An opaque type which represents a mark on a stream. There is no
888 * concrete definition of this type, it is a named type for stream
889 * implementation specific baton pointers.
891 * @see svn_stream_mark().
894 typedef struct svn_stream_mark_t svn_stream_mark_t;
896 /** Mark handler function for a generic stream. @see svn_stream_t and
901 typedef svn_error_t *(*svn_stream_mark_fn_t)(void *baton,
902 svn_stream_mark_t **mark,
905 /** Seek handler function for a generic stream. @see svn_stream_t and
910 typedef svn_error_t *(*svn_stream_seek_fn_t)(void *baton,
911 const svn_stream_mark_t *mark);
913 /** Poll handler for generic streams that support incomplete reads, @see
914 * svn_stream_t and svn_stream_data_available().
918 typedef svn_error_t *(*svn_stream_data_available_fn_t)(void *baton,
919 svn_boolean_t *data_available);
921 /** Readline handler function for a generic stream. @see svn_stream_t and
922 * svn_stream_readline().
924 * @since New in 1.10.
926 typedef svn_error_t *(*svn_stream_readline_fn_t)(void *baton,
927 svn_stringbuf_t **stringbuf,
932 /** Create a generic stream. @see svn_stream_t. */
934 svn_stream_create(void *baton,
937 /** Set @a stream's baton to @a baton */
939 svn_stream_set_baton(svn_stream_t *stream,
942 /** Set @a stream's read functions to @a read_fn and @a read_full_fn. If
943 * @a read_full_fn is NULL a default implementation based on multiple calls
944 * to @a read_fn will be used.
949 svn_stream_set_read2(svn_stream_t *stream,
950 svn_read_fn_t read_fn,
951 svn_read_fn_t read_full_fn);
953 /** Set @a stream's read function to @a read_fn.
955 * This function sets only the full read function to read_fn.
957 * @deprecated Provided for backward compatibility with the 1.8 API.
961 svn_stream_set_read(svn_stream_t *stream,
962 svn_read_fn_t read_fn);
964 /** Set @a stream's skip function to @a skip_fn
969 svn_stream_set_skip(svn_stream_t *stream,
970 svn_stream_skip_fn_t skip_fn);
972 /** Set @a stream's write function to @a write_fn */
974 svn_stream_set_write(svn_stream_t *stream,
975 svn_write_fn_t write_fn);
977 /** Set @a stream's close function to @a close_fn */
979 svn_stream_set_close(svn_stream_t *stream,
980 svn_close_fn_t close_fn);
982 /** Set @a stream's mark function to @a mark_fn
987 svn_stream_set_mark(svn_stream_t *stream,
988 svn_stream_mark_fn_t mark_fn);
990 /** Set @a stream's seek function to @a seek_fn
995 svn_stream_set_seek(svn_stream_t *stream,
996 svn_stream_seek_fn_t seek_fn);
998 /** Set @a stream's data available function to @a data_available_fn
1000 * @since New in 1.9.
1003 svn_stream_set_data_available(svn_stream_t *stream,
1004 svn_stream_data_available_fn_t data_available);
1006 /** Set @a stream's readline function to @a readline_fn
1008 * @since New in 1.10.
1011 svn_stream_set_readline(svn_stream_t *stream,
1012 svn_stream_readline_fn_t readline_fn);
1014 /** Create a stream that is empty for reading and infinite for writing. */
1016 svn_stream_empty(apr_pool_t *pool);
1018 /** Return a stream allocated in @a pool which forwards all requests
1019 * to @a stream. Destruction is explicitly excluded from forwarding.
1021 * @see http://subversion.apache.org/docs/community-guide/conventions.html#destruction-of-stacked-resources
1023 * @since New in 1.4.
1026 svn_stream_disown(svn_stream_t *stream,
1030 /** Create a stream to read the file at @a path. It will be opened using
1031 * the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the perms.
1032 * If you'd like to use different values, then open the file yourself, and
1033 * use the svn_stream_from_aprfile2() interface.
1035 * The stream will be returned in @a stream, and allocated from @a result_pool.
1036 * Temporary allocations will be performed in @a scratch_pool.
1041 svn_stream_open_readonly(svn_stream_t **stream,
1043 apr_pool_t *result_pool,
1044 apr_pool_t *scratch_pool);
1047 /** Create a stream to write a file at @a path. The file will be *created*
1048 * using the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the
1049 * perms. The file will be created "exclusively", so if it already exists,
1050 * then an error will be thrown. If you'd like to use different values, or
1051 * open an existing file, then open the file yourself, and use the
1052 * svn_stream_from_aprfile2() interface.
1054 * The stream will be returned in @a stream, and allocated from @a result_pool.
1055 * Temporary allocations will be performed in @a scratch_pool.
1060 svn_stream_open_writable(svn_stream_t **stream,
1062 apr_pool_t *result_pool,
1063 apr_pool_t *scratch_pool);
1066 /** Create a writable stream to a file in the directory @a dirpath.
1067 * The file will have an arbitrary and unique name, and the full path
1068 * will be returned in @a temp_path. The stream will be returned in
1069 * @a stream. Both will be allocated from @a result_pool.
1071 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
1072 * (Note that when using the system-provided temp directory, it may not
1073 * be possible to atomically rename the resulting file due to cross-device
1076 * The file will be deleted according to @a delete_when. If that is
1077 * #svn_io_file_del_on_pool_cleanup, it refers to @a result_pool.
1079 * Temporary allocations will be performed in @a scratch_pool.
1082 * @see svn_io_open_unique_file3()
1085 svn_stream_open_unique(svn_stream_t **stream,
1086 const char **temp_path,
1087 const char *dirpath,
1088 svn_io_file_del_t delete_when,
1089 apr_pool_t *result_pool,
1090 apr_pool_t *scratch_pool);
1093 /** Create a stream from an APR file. For convenience, if @a file is
1094 * @c NULL, an empty stream created by svn_stream_empty() is returned.
1096 * This function should normally be called with @a disown set to FALSE,
1097 * in which case closing the stream will also close the underlying file.
1099 * If @a disown is TRUE, the stream will disown the underlying file,
1100 * meaning that svn_stream_close() will not close the file.
1102 * @since New in 1.4.
1105 svn_stream_from_aprfile2(apr_file_t *file,
1106 svn_boolean_t disown,
1109 /** Similar to svn_stream_from_aprfile2(), except that the file will
1110 * always be disowned.
1112 * @note The stream returned is not considered to "own" the underlying
1113 * file, meaning that svn_stream_close() on the stream will not
1116 * @deprecated Provided for backward compatibility with the 1.3 API.
1120 svn_stream_from_aprfile(apr_file_t *file,
1123 /** Set @a *in to a generic stream connected to stdin, allocated in
1124 * @a pool. If @a buffered is set, APR buffering will be enabled.
1125 * The stream and its underlying APR handle will be closed when @a pool
1126 * is cleared or destroyed.
1128 * @note APR buffering will try to fill the whole internal buffer before
1129 * serving read requests. This may be inappropriate for interactive
1130 * applications where stdin will not deliver any more data unless
1131 * the application processed the data already received.
1133 * @since New in 1.10.
1136 svn_stream_for_stdin2(svn_stream_t **in,
1137 svn_boolean_t buffered,
1140 /** Similar to svn_stream_for_stdin2(), but with buffering being disabled.
1142 * @since New in 1.7.
1144 * @deprecated Provided for backward compatibility with the 1.9 API.
1148 svn_stream_for_stdin(svn_stream_t **in,
1151 /** Set @a *err to a generic stream connected to stderr, allocated in
1152 * @a pool. The stream and its underlying APR handle will be closed
1153 * when @a pool is cleared or destroyed.
1155 * @since New in 1.7.
1158 svn_stream_for_stderr(svn_stream_t **err,
1161 /** Set @a *out to a generic stream connected to stdout, allocated in
1162 * @a pool. The stream and its underlying APR handle will be closed
1163 * when @a pool is cleared or destroyed.
1166 svn_stream_for_stdout(svn_stream_t **out,
1169 /** Read the contents of @a stream into memory, from its current position
1170 * to its end, returning the data in @a *result. This function does not
1171 * close the @a stream upon completion.
1173 * @a len_hint gives a hint about the expected length, in bytes, of the
1174 * actual data that will be read from the stream. It may be 0, meaning no
1175 * hint is being provided. Efficiency in time and/or in space may be
1176 * better (and in general will not be worse) when the actual data length
1177 * is equal or approximately equal to the length hint.
1179 * The returned memory is allocated in @a result_pool.
1181 * @note The present implementation is efficient when @a len_hint is big
1182 * enough (but not vastly bigger than necessary), and also for actual
1183 * lengths up to 64 bytes when @a len_hint is 0. Otherwise it can incur
1184 * significant time and space overheads. See source code for details.
1186 * @since New in 1.9.
1189 svn_stringbuf_from_stream(svn_stringbuf_t **result,
1190 svn_stream_t *stream,
1191 apr_size_t len_hint,
1192 apr_pool_t *result_pool);
1194 /** Return a generic stream connected to stringbuf @a str. Allocate the
1195 * stream in @a pool.
1198 svn_stream_from_stringbuf(svn_stringbuf_t *str,
1201 /** Return a generic read-only stream connected to string @a str.
1202 * Allocate the stream in @a pool.
1205 svn_stream_from_string(const svn_string_t *str,
1208 /** Return a generic stream which implements buffered reads and writes.
1209 * The stream will preferentially store data in-memory, but may use
1210 * disk storage as backup if the amount of data is large.
1211 * Allocate the stream in @a result_pool
1213 * @since New in 1.8.
1216 svn_stream_buffered(apr_pool_t *result_pool);
1218 /** Return a stream that decompresses all data read and compresses all
1219 * data written. The stream @a stream is used to read and write all
1220 * compressed data. All compression data structures are allocated on
1221 * @a pool. If compression support is not compiled in then
1222 * svn_stream_compressed() returns @a stream unmodified. Make sure you
1223 * call svn_stream_close() on the stream returned by this function,
1224 * so that all data are flushed and cleaned up.
1226 * @note From 1.4, compression support is always compiled in.
1229 svn_stream_compressed(svn_stream_t *stream,
1232 /** Return a stream that calculates checksums for all data read
1233 * and written. The stream @a stream is used to read and write all data.
1234 * The stream and the resulting digests are allocated in @a pool.
1236 * When the stream is closed, @a *read_checksum and @a *write_checksum
1237 * are set to point to the resulting checksums, of type @a read_checksum_kind
1238 * and @a write_checksum_kind, respectively.
1240 * Both @a read_checksum and @a write_checksum can be @c NULL, in which case
1241 * the respective checksum isn't calculated.
1243 * If @a read_all is TRUE, make sure that all data available on @a
1244 * stream is read (and checksummed) when the stream is closed.
1246 * Read and write operations can be mixed without interfering.
1248 * The @a stream passed into this function is closed when the created
1251 * @since New in 1.6. Since 1.10, the resulting stream supports reset
1252 * via stream_stream_reset().
1255 svn_stream_checksummed2(svn_stream_t *stream,
1256 svn_checksum_t **read_checksum,
1257 svn_checksum_t **write_checksum,
1258 svn_checksum_kind_t checksum_kind,
1259 svn_boolean_t read_all,
1263 * Similar to svn_stream_checksummed2(), but always returning the MD5
1264 * checksum in @a read_digest and @a write_digest.
1266 * @since New in 1.4.
1267 * @deprecated Provided for backward compatibility with the 1.5 API.
1271 svn_stream_checksummed(svn_stream_t *stream,
1272 const unsigned char **read_digest,
1273 const unsigned char **write_digest,
1274 svn_boolean_t read_all,
1277 /** Read the contents of the readable stream @a stream and return its
1278 * checksum of type @a kind in @a *checksum.
1280 * The stream will be closed before this function returns (regardless
1281 * of the result, or any possible error).
1283 * Use @a scratch_pool for temporary allocations and @a result_pool
1284 * to allocate @a *checksum.
1286 * @since New in 1.10.
1289 svn_stream_contents_checksum(svn_checksum_t **checksum,
1290 svn_stream_t *stream,
1291 svn_checksum_kind_t kind,
1292 apr_pool_t *result_pool,
1293 apr_pool_t *scratch_pool);
1295 /** Read from a generic stream until @a buffer is filled upto @a *len or
1296 * until EOF is reached. @see svn_stream_t
1298 * @since New in 1.9.
1301 svn_stream_read_full(svn_stream_t *stream,
1306 /** Returns @c TRUE if the generic @c stream supports svn_stream_read2().
1308 * @since New in 1.9.
1311 svn_stream_supports_partial_read(svn_stream_t *stream);
1313 /** Read all currently available upto @a *len into @a buffer. Use
1314 * svn_stream_read_full() if you want to wait for the buffer to be filled
1315 * or EOF. If the stream doesn't support limited reads this function will
1316 * return an #SVN_ERR_STREAM_NOT_SUPPORTED error.
1318 * A 0 byte read signals the end of the stream.
1320 * @since New in 1.9.
1323 svn_stream_read2(svn_stream_t *stream,
1328 /** Read from a generic stream until the buffer is completely filled or EOF.
1329 * @see svn_stream_t.
1331 * @note This function is a wrapper of svn_stream_read_full() now, which name
1332 * better documents the behavior of this function.
1334 * @deprecated Provided for backward compatibility with the 1.8 API
1338 svn_stream_read(svn_stream_t *stream,
1343 * Skip @a len bytes from a generic @a stream. If the stream is exhausted
1344 * before @a len bytes have been read, return an error.
1346 * @note No assumption can be made on the semantics of this function
1347 * other than that the stream read pointer will be advanced by *len
1348 * bytes. Depending on the capabilities of the underlying stream
1349 * implementation, this may for instance be translated into a sequence
1350 * of reads or a simple seek operation. If the stream implementation has
1351 * not provided a skip function, this will read from the stream and
1354 * @since New in 1.7.
1357 svn_stream_skip(svn_stream_t *stream,
1360 /** Write to a generic stream. @see svn_stream_t. */
1362 svn_stream_write(svn_stream_t *stream,
1366 /** Close a generic stream. @see svn_stream_t. */
1368 svn_stream_close(svn_stream_t *stream);
1370 /** Reset a generic stream back to its origin. (E.g. On a file this would be
1371 * implemented as a seek to position 0). This function returns a
1372 * #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error when the stream doesn't
1373 * implement resetting.
1375 * @since New in 1.7.
1378 svn_stream_reset(svn_stream_t *stream);
1380 /** Returns @c TRUE if the generic @a stream supports svn_stream_mark().
1382 * @see svn_stream_mark()
1383 * @since New in 1.7.
1386 svn_stream_supports_mark(svn_stream_t *stream);
1388 /** Returns @c TRUE if the generic @a stream supports svn_stream_reset().
1390 * @see svn_stream_reset()
1391 * @since New in 1.10.
1394 svn_stream_supports_reset(svn_stream_t *stream);
1396 /** Set a @a mark at the current position of a generic @a stream,
1397 * which can later be sought back to using svn_stream_seek().
1398 * The @a mark is allocated in @a pool.
1400 * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error
1401 * if the stream doesn't implement seeking.
1403 * @see svn_stream_seek()
1404 * @since New in 1.7.
1407 svn_stream_mark(svn_stream_t *stream,
1408 svn_stream_mark_t **mark,
1411 /** Seek to a @a mark in a generic @a stream.
1412 * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error
1413 * if the stream doesn't implement seeking. Passing NULL as @a mark,
1414 * seeks to the start of the stream.
1416 * @see svn_stream_mark()
1417 * @since New in 1.7.
1420 svn_stream_seek(svn_stream_t *stream, const svn_stream_mark_t *mark);
1422 /** When a stream supports polling for available data, obtain a boolean
1423 * indicating whether data is waiting to be read. If the stream doesn't
1424 * support polling this function returns a #SVN_ERR_STREAM_NOT_SUPPORTED
1427 * If the data_available callback is implemented and the stream is at the end
1428 * the stream will set @a *data_available to FALSE.
1430 * @since New in 1.9.
1433 svn_stream_data_available(svn_stream_t *stream,
1434 svn_boolean_t *data_available);
1436 /** Return a writable stream which, when written to, writes to both of the
1437 * underlying streams. Both of these streams will be closed upon closure of
1438 * the returned stream; use svn_stream_disown() if this is not the desired
1439 * behavior. One or both of @a out1 and @a out2 may be @c NULL. If both are
1440 * @c NULL, @c NULL is returned.
1442 * @since New in 1.7.
1445 svn_stream_tee(svn_stream_t *out1,
1449 /** Write NULL-terminated string @a str to @a stream.
1451 * @since New in 1.8.
1455 svn_stream_puts(svn_stream_t *stream,
1458 /** Write to @a stream using a printf-style @a fmt specifier, passed through
1459 * apr_psprintf() using memory from @a pool.
1462 svn_stream_printf(svn_stream_t *stream,
1466 __attribute__((format(printf, 3, 4)));
1468 /** Write to @a stream using a printf-style @a fmt specifier, passed through
1469 * apr_psprintf() using memory from @a pool. The resulting string
1470 * will be translated to @a encoding before it is sent to @a stream.
1472 * @note Use @c APR_LOCALE_CHARSET to translate to the encoding of the
1475 * @since New in 1.3.
1478 svn_stream_printf_from_utf8(svn_stream_t *stream,
1479 const char *encoding,
1483 __attribute__((format(printf, 4, 5)));
1485 /** Allocate @a *stringbuf in @a pool, and read into it one line (terminated
1486 * by @a eol) from @a stream. The line-terminator is read from the stream,
1487 * but is not added to the end of the stringbuf. Instead, the stringbuf
1488 * ends with a usual '\\0'.
1490 * If @a stream runs out of bytes before encountering a line-terminator,
1491 * then set @a *eof to @c TRUE, otherwise set @a *eof to FALSE.
1494 svn_stream_readline(svn_stream_t *stream,
1495 svn_stringbuf_t **stringbuf,
1501 * Read the contents of the readable stream @a from and write them to the
1502 * writable stream @a to calling @a cancel_func before copying each chunk.
1504 * @a cancel_func may be @c NULL.
1506 * @note both @a from and @a to will be closed upon successful completion of
1507 * the copy (but an error may still be returned, based on trying to close
1508 * the two streams). If the closure is not desired, then you can use
1509 * svn_stream_disown() to protect either or both of the streams from
1512 * @since New in 1.6.
1515 svn_stream_copy3(svn_stream_t *from,
1517 svn_cancel_func_t cancel_func,
1522 * Same as svn_stream_copy3() but the streams are not closed.
1524 * @since New in 1.5.
1525 * @deprecated Provided for backward compatibility with the 1.5 API.
1529 svn_stream_copy2(svn_stream_t *from,
1531 svn_cancel_func_t cancel_func,
1536 * Same as svn_stream_copy3(), but without the cancellation function
1537 * or stream closing.
1539 * @since New in 1.1.
1540 * @deprecated Provided for backward compatibility with the 1.4 API.
1544 svn_stream_copy(svn_stream_t *from,
1549 /** Set @a *same to TRUE if @a stream1 and @a stream2 have the same
1550 * contents, else set it to FALSE.
1552 * Both streams will be closed before this function returns (regardless of
1553 * the result, or any possible error).
1555 * Use @a scratch_pool for temporary allocations.
1557 * @since New in 1.7.
1560 svn_stream_contents_same2(svn_boolean_t *same,
1561 svn_stream_t *stream1,
1562 svn_stream_t *stream2,
1567 * Same as svn_stream_contents_same2(), but the streams will not be closed.
1569 * @since New in 1.4.
1570 * @deprecated Provided for backward compatibility with the 1.6 API.
1574 svn_stream_contents_same(svn_boolean_t *same,
1575 svn_stream_t *stream1,
1576 svn_stream_t *stream2,
1580 /** Read the contents of @a stream into memory, from its current position
1581 * to its end, returning the data in @a *result. The stream will be closed
1582 * when it has been successfully and completely read.
1584 * @a len_hint gives a hint about the expected length, in bytes, of the
1585 * actual data that will be read from the stream. It may be 0, meaning no
1586 * hint is being provided. Efficiency in time and/or in space may be
1587 * better (and in general will not be worse) when the actual data length
1588 * is equal or approximately equal to the length hint.
1590 * The returned memory is allocated in @a result_pool, and any temporary
1591 * allocations may be performed in @a scratch_pool.
1593 * @note The present implementation is efficient when @a len_hint is big
1594 * enough (but not vastly bigger than necessary), and also for actual
1595 * lengths up to 64 bytes when @a len_hint is 0. Otherwise it can incur
1596 * significant time and space overheads. See source code for details.
1598 * @since New in 1.10
1601 svn_string_from_stream2(svn_string_t **result,
1602 svn_stream_t *stream,
1603 apr_size_t len_hint,
1604 apr_pool_t *result_pool);
1606 /** Similar to svn_string_from_stream2(), but always passes 0 for
1609 * @deprecated Provided for backwards compatibility with the 1.9 API.
1613 svn_string_from_stream(svn_string_t **result,
1614 svn_stream_t *stream,
1615 apr_pool_t *result_pool,
1616 apr_pool_t *scratch_pool);
1618 /** A function type provided for use as a callback from
1619 * @c svn_stream_lazyopen_create().
1621 * The callback function shall open a new stream and set @a *stream to
1622 * the stream object, allocated in @a result_pool. @a baton is the
1623 * callback baton that was passed to svn_stream_lazyopen_create().
1625 * @a result_pool is the result pool that was passed to
1626 * svn_stream_lazyopen_create(). The callback function may use
1627 * @a scratch_pool for temporary allocations; the caller may clear or
1628 * destroy @a scratch_pool any time after the function returns.
1630 * @since New in 1.8.
1632 typedef svn_error_t *
1633 (*svn_stream_lazyopen_func_t)(svn_stream_t **stream,
1635 apr_pool_t *result_pool,
1636 apr_pool_t *scratch_pool);
1639 /** Return a generic stream which wraps another primary stream,
1640 * delaying the "opening" of that stream until the first time the
1641 * returned stream is accessed.
1643 * @a open_func and @a open_baton are a callback function/baton pair
1644 * which will be invoked upon the first access of the returned
1645 * stream (read, write, mark, seek, skip, or possibly close). The
1646 * callback shall open the primary stream.
1648 * If the only "access" the returned stream gets is to close it
1649 * then @a open_func will only be called if @a open_on_close is TRUE.
1651 * Allocate the returned stream in @a result_pool. Also arrange for
1652 * @a result_pool to be passed as the @c result_pool parameter to
1653 * @a open_func when it is called.
1655 * @since New in 1.8.
1658 svn_stream_lazyopen_create(svn_stream_lazyopen_func_t open_func,
1660 svn_boolean_t open_on_close,
1661 apr_pool_t *result_pool);
1665 /** Set @a *result to a string containing the contents of @a
1666 * filename, which is either "-" (indicating that stdin should be
1667 * read) or the utf8-encoded path of a real file.
1669 * @warning Callers should be aware of possible unexpected results
1670 * when using this function to read from stdin where additional
1671 * stdin-reading processes abound. For example, if a program tries
1672 * both to invoke an external editor and to read from stdin, stdin
1673 * could be trashed and the editor might act funky or die outright.
1675 * @note due to memory pseudo-reallocation behavior (due to pools), this
1676 * can be a memory-intensive operation for large files.
1678 * @since New in 1.5.
1681 svn_stringbuf_from_file2(svn_stringbuf_t **result,
1682 const char *filename,
1685 /** Similar to svn_stringbuf_from_file2(), except that if @a filename
1686 * is "-", return the error #SVN_ERR_UNSUPPORTED_FEATURE and don't
1689 * @deprecated Provided for backwards compatibility with the 1.4 API.
1693 svn_stringbuf_from_file(svn_stringbuf_t **result,
1694 const char *filename,
1697 /** Sets @a *result to a string containing the contents of the already opened
1698 * @a file. Reads from the current position in file to the end. Does not
1699 * close the file or reset the cursor position.
1701 * @note due to memory pseudo-reallocation behavior (due to pools), this
1702 * can be a memory-intensive operation for large files.
1705 svn_stringbuf_from_aprfile(svn_stringbuf_t **result,
1709 /** Remove file @a path, a utf8-encoded path. This wraps apr_file_remove(),
1710 * converting any error to a Subversion error. If @a ignore_enoent is TRUE, and
1711 * the file is not present (APR_STATUS_IS_ENOENT returns TRUE), then no
1712 * error will be returned.
1714 * The file will be removed even if it is not writable. (On Windows and
1715 * OS/2, this function first clears the file's read-only bit.)
1717 * @since New in 1.7.
1720 svn_io_remove_file2(const char *path,
1721 svn_boolean_t ignore_enoent,
1722 apr_pool_t *scratch_pool);
1724 /** Similar to svn_io_remove_file2(), except with @a ignore_enoent set to FALSE.
1726 * @deprecated Provided for backwards compatibility with the 1.6 API.
1730 svn_io_remove_file(const char *path,
1733 /** Recursively remove directory @a path. @a path is utf8-encoded.
1734 * If @a ignore_enoent is @c TRUE, don't fail if the target directory
1735 * doesn't exist. Use @a pool for temporary allocations.
1737 * Because recursive delete of a directory tree can be a lengthy operation,
1738 * provide @a cancel_func and @a cancel_baton for interruptibility.
1740 * @since New in 1.5.
1743 svn_io_remove_dir2(const char *path,
1744 svn_boolean_t ignore_enoent,
1745 svn_cancel_func_t cancel_func,
1749 /** Similar to svn_io_remove_dir2(), but with @a ignore_enoent set to
1750 * @c FALSE and @a cancel_func and @a cancel_baton set to @c NULL.
1752 * @deprecated Provided for backward compatibility with the 1.4 API
1756 svn_io_remove_dir(const char *path,
1759 /** Read all of the disk entries in directory @a path, a utf8-encoded
1760 * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
1761 * undefined non-NULL values, allocated in @a pool.
1763 * @note The `.' and `..' directories normally returned by
1764 * apr_dir_read() are NOT returned in the hash.
1766 * @since New in 1.4.
1767 * @deprecated Provided for backward compatibility with the 1.6 API.
1771 svn_io_get_dir_filenames(apr_hash_t **dirents,
1775 /** Read all of the disk entries in directory @a path, a utf8-encoded
1776 * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
1777 * #svn_io_dirent2_t structures, allocated in @a pool.
1779 * If @a only_check_type is set to @c TRUE, only the kind and special
1780 * fields of the svn_io_dirent2_t are filled.
1782 * @note The `.' and `..' directories normally returned by
1783 * apr_dir_read() are NOT returned in the hash.
1785 * @note The kind field in the @a dirents is set according to the mapping
1786 * as documented for svn_io_check_path().
1788 * @since New in 1.7.
1791 svn_io_get_dirents3(apr_hash_t **dirents,
1793 svn_boolean_t only_check_type,
1794 apr_pool_t *result_pool,
1795 apr_pool_t *scratch_pool);
1798 /** Similar to svn_io_get_dirents3, but returns a mapping to svn_io_dirent_t
1799 * structures instead of svn_io_dirent2_t and with only a single pool.
1801 * @since New in 1.3.
1802 * @deprecated Provided for backward compatibility with the 1.6 API.
1806 svn_io_get_dirents2(apr_hash_t **dirents,
1810 /** Similar to svn_io_get_dirents2(), but @a *dirents is a hash table
1811 * with #svn_node_kind_t values.
1813 * @deprecated Provided for backwards compatibility with the 1.2 API.
1817 svn_io_get_dirents(apr_hash_t **dirents,
1821 /** Create a svn_io_dirent2_t instance for path. Specialized variant of
1822 * svn_io_stat() that directly translates node_kind and special.
1824 * If @a verify_truename is @c TRUE, an additional check is performed to
1825 * verify the truename of the last path component on case insensitive
1826 * filesystems. This check is expensive compared to a just a stat,
1827 * but certainly cheaper than a full truename calculation using
1828 * apr_filepath_merge() which verifies all path components.
1830 * If @a ignore_enoent is set to @c TRUE, set *dirent_p->kind to
1831 * svn_node_none instead of returning an error.
1833 * @since New in 1.8.
1836 svn_io_stat_dirent2(const svn_io_dirent2_t **dirent_p,
1838 svn_boolean_t verify_truename,
1839 svn_boolean_t ignore_enoent,
1840 apr_pool_t *result_pool,
1841 apr_pool_t *scratch_pool);
1844 /** Similar to svn_io_stat_dirent2(), but always passes FALSE for
1845 * @a verify_truename.
1847 * @since New in 1.7.
1848 * @deprecated Provided for backwards compatibility with the 1.7 API.
1852 svn_io_stat_dirent(const svn_io_dirent2_t **dirent_p,
1854 svn_boolean_t ignore_enoent,
1855 apr_pool_t *result_pool,
1856 apr_pool_t *scratch_pool);
1859 /** Callback function type for svn_io_dir_walk() */
1860 typedef svn_error_t * (*svn_io_walk_func_t)(void *baton,
1862 const apr_finfo_t *finfo,
1865 /** Recursively walk the directory rooted at @a dirname, a
1866 * utf8-encoded path, invoking @a walk_func (with @a walk_baton) for
1867 * each item in the tree. For a given directory, invoke @a walk_func
1868 * on the directory itself before invoking it on any children thereof.
1870 * Deliver to @a walk_func the information specified by @a wanted,
1871 * which is a combination of @c APR_FINFO_* flags, plus the
1872 * information specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME.
1874 * Use @a pool for all allocations.
1876 * @note This function does not currently pass all file types to @a
1877 * walk_func -- only APR_DIR, APR_REG, and APR_LNK. We reserve the
1878 * right to pass additional file types through this interface in the
1879 * future, though, so implementations of this callback should
1880 * explicitly test FINFO->filetype. See the APR library's
1881 * apr_filetype_e enum for the various filetypes and their meanings.
1883 * @since New in 1.7.
1886 svn_io_dir_walk2(const char *dirname,
1888 svn_io_walk_func_t walk_func,
1892 /** Similar to svn_io_dir_walk(), but only calls @a walk_func for
1893 * files of type APR_DIR (directory) and APR_REG (regular file).
1895 * @deprecated Provided for backwards compatibility with the 1.6 API.
1899 svn_io_dir_walk(const char *dirname,
1901 svn_io_walk_func_t walk_func,
1906 * Start @a cmd with @a args, using utf8-encoded @a path as working
1907 * directory. Return the process handle for the invoked program in @a
1910 * If @a infile_pipe is TRUE, connect @a cmd's stdin to a pipe;
1911 * otherwise, connect it to @a infile (which may be NULL). If
1912 * @a outfile_pipe is TRUE, connect @a cmd's stdout to a pipe; otherwise,
1913 * connect it to @a outfile (which may be NULL). If @a errfile_pipe
1914 * is TRUE, connect @a cmd's stderr to a pipe; otherwise, connect it
1915 * to @a errfile (which may be NULL). (Callers must pass FALSE for
1916 * each of these boolean values for which the corresponding file
1917 * handle is non-NULL.)
1919 * @a args is a list of utf8-encoded <tt>const char *</tt> arguments,
1920 * terminated by @c NULL. @a args[0] is the name of the program, though it
1921 * need not be the same as @a cmd.
1923 * If @a inherit is TRUE, the invoked program inherits its environment from
1924 * the caller and @a cmd, if not absolute, is searched for in PATH.
1926 * If @a inherit is FALSE @a cmd must be an absolute path and the invoked
1927 * program inherits the environment defined by @a env or runs with an empty
1928 * environment in @a env is NULL.
1930 * @note On some platforms, failure to execute @a cmd in the child process
1931 * will result in error output being written to @a errfile, if non-NULL, and
1932 * a non-zero exit status being returned to the parent process.
1934 * @note An APR bug affects Windows: passing a NULL @a env does not
1935 * guarantee the invoked program to run with an empty environment when
1936 * @a inherit is FALSE, the program may inherit its parent's environment.
1937 * Explicitly pass an empty @a env to get an empty environment.
1939 * @since New in 1.8.
1941 svn_error_t *svn_io_start_cmd3(apr_proc_t *cmd_proc,
1944 const char *const *args,
1945 const char *const *env,
1946 svn_boolean_t inherit,
1947 svn_boolean_t infile_pipe,
1949 svn_boolean_t outfile_pipe,
1950 apr_file_t *outfile,
1951 svn_boolean_t errfile_pipe,
1952 apr_file_t *errfile,
1957 * Similar to svn_io_start_cmd3() but with @a env always set to NULL.
1959 * @deprecated Provided for backward compatibility with the 1.7 API
1960 * @since New in 1.7.
1963 svn_error_t *svn_io_start_cmd2(apr_proc_t *cmd_proc,
1966 const char *const *args,
1967 svn_boolean_t inherit,
1968 svn_boolean_t infile_pipe,
1970 svn_boolean_t outfile_pipe,
1971 apr_file_t *outfile,
1972 svn_boolean_t errfile_pipe,
1973 apr_file_t *errfile,
1977 * Similar to svn_io_start_cmd2() but with @a infile_pipe, @a
1978 * outfile_pipe, and @a errfile_pipe always FALSE.
1980 * @deprecated Provided for backward compatibility with the 1.6 API
1981 * @since New in 1.3.
1985 svn_io_start_cmd(apr_proc_t *cmd_proc,
1988 const char *const *args,
1989 svn_boolean_t inherit,
1991 apr_file_t *outfile,
1992 apr_file_t *errfile,
1996 * Wait for the process @a *cmd_proc to complete and optionally retrieve
1997 * its exit code. @a cmd is used only in error messages.
1999 * If @a exitcode is not NULL, set @a *exitcode to the exit code of the
2000 * process and do not consider any exit code to be an error. If @a exitcode
2001 * is NULL, then if the exit code of the process is non-zero then return an
2002 * #SVN_ERR_EXTERNAL_PROGRAM error.
2004 * If @a exitwhy is not NULL, set @a *exitwhy to indicate why the process
2005 * terminated and do not consider any reason to be an error. If @a exitwhy
2006 * is NULL, then if the termination reason is not @c APR_PROC_CHECK_EXIT()
2007 * then return an #SVN_ERR_EXTERNAL_PROGRAM error.
2009 * @since New in 1.3.
2012 svn_io_wait_for_cmd(apr_proc_t *cmd_proc,
2015 apr_exit_why_e *exitwhy,
2018 /** Run a command to completion, by first calling svn_io_start_cmd() and
2019 * then calling svn_io_wait_for_cmd(). The parameters correspond to
2020 * the same-named parameters of those two functions.
2023 svn_io_run_cmd(const char *path,
2025 const char *const *args,
2027 apr_exit_why_e *exitwhy,
2028 svn_boolean_t inherit,
2030 apr_file_t *outfile,
2031 apr_file_t *errfile,
2034 /** Invoke the configured @c diff program, with @a user_args (an array
2035 * of utf8-encoded @a num_user_args arguments) if they are specified
2036 * (that is, if @a user_args is non-NULL), or "-u" if they are not.
2037 * If @a user_args is NULL, the value of @a num_user_args is ignored.
2039 * Diff runs in utf8-encoded @a dir, and its exit status is stored in
2040 * @a exitcode, if it is not @c NULL.
2042 * If @a label1 and/or @a label2 are not NULL they will be passed to the diff
2043 * process as the arguments of "-L" options. @a label1 and @a label2 are also
2044 * in utf8, and will be converted to native charset along with the other args.
2046 * @a from is the first file passed to diff, and @a to is the second. The
2047 * stdout of diff will be sent to @a outfile, and the stderr to @a errfile.
2049 * @a diff_cmd must be non-NULL.
2051 * Do all allocation in @a pool.
2052 * @since New in 1.6.0.
2055 svn_io_run_diff2(const char *dir,
2056 const char *const *user_args,
2063 apr_file_t *outfile,
2064 apr_file_t *errfile,
2065 const char *diff_cmd,
2068 /** Similar to svn_io_run_diff2() but with @a diff_cmd encoded in internal
2069 * encoding used by APR.
2071 * @deprecated Provided for backwards compatibility with the 1.5 API. */
2074 svn_io_run_diff(const char *dir,
2075 const char *const *user_args,
2082 apr_file_t *outfile,
2083 apr_file_t *errfile,
2084 const char *diff_cmd,
2089 /** Invoke the configured @c diff3 program, in utf8-encoded @a dir
2092 * diff3 -E -m @a mine @a older @a yours > @a merged
2094 * (See the diff3 documentation for details.)
2096 * If @a user_args is non-NULL, replace "-E" with the <tt>const char*</tt>
2097 * elements that @a user_args contains.
2099 * @a mine, @a older and @a yours are utf8-encoded paths (relative to
2100 * @a dir or absolute) to three files that already exist.
2102 * @a merged is an open file handle, and is left open after the merge
2103 * result is written to it. (@a merged should *not* be the same file
2104 * as @a mine, or nondeterministic things may happen!)
2106 * @a mine_label, @a older_label, @a yours_label are utf8-encoded label
2107 * parameters for diff3's -L option. Any of them may be @c NULL, in
2108 * which case the corresponding @a mine, @a older, or @a yours parameter is
2111 * Set @a *exitcode to diff3's exit status. If @a *exitcode is anything
2112 * other than 0 or 1, then return #SVN_ERR_EXTERNAL_PROGRAM. (Note the
2113 * following from the diff3 info pages: "An exit status of 0 means
2114 * `diff3' was successful, 1 means some conflicts were found, and 2
2117 * @a diff3_cmd must be non-NULL.
2119 * Do all allocation in @a pool.
2121 * @since New in 1.4.
2124 svn_io_run_diff3_3(int *exitcode,
2129 const char *mine_label,
2130 const char *older_label,
2131 const char *yours_label,
2133 const char *diff3_cmd,
2134 const apr_array_header_t *user_args,
2137 /** Similar to svn_io_run_diff3_3(), but with @a diff3_cmd encoded in
2138 * internal encoding used by APR.
2140 * @deprecated Provided for backwards compatibility with the 1.5 API.
2141 * @since New in 1.4.
2145 svn_io_run_diff3_2(int *exitcode,
2150 const char *mine_label,
2151 const char *older_label,
2152 const char *yours_label,
2154 const char *diff3_cmd,
2155 const apr_array_header_t *user_args,
2158 /** Similar to svn_io_run_diff3_2(), but with @a user_args set to @c NULL.
2160 * @deprecated Provided for backwards compatibility with the 1.3 API.
2164 svn_io_run_diff3(const char *dir,
2168 const char *mine_label,
2169 const char *older_label,
2170 const char *yours_label,
2173 const char *diff3_cmd,
2177 /** Parse utf8-encoded @a mimetypes_file as a MIME types file (such as
2178 * is provided with Apache HTTP Server), and set @a *type_map to a
2179 * hash mapping <tt>const char *</tt> filename extensions to
2180 * <tt>const char *</tt> MIME types.
2182 * @since New in 1.5.
2185 svn_io_parse_mimetypes_file(apr_hash_t **type_map,
2186 const char *mimetypes_file,
2190 /** Examine utf8-encoded @a file to determine if it can be described by a
2191 * known (as in, known by this function) Multipurpose Internet Mail
2192 * Extension (MIME) type. If so, set @a *mimetype to a character string
2193 * describing the MIME type, else set it to @c NULL.
2195 * If not @c NULL, @a mimetype_map is a hash mapping <tt>const char *</tt>
2196 * filename extensions to <tt>const char *</tt> MIME types, and is the
2197 * first source consulted regarding @a file's MIME type.
2199 * Use @a pool for any necessary allocations.
2201 * @since New in 1.5.
2204 svn_io_detect_mimetype2(const char **mimetype,
2206 apr_hash_t *mimetype_map,
2210 /** Like svn_io_detect_mimetype2, but with @a mimetypes_map set to
2213 * @deprecated Provided for backward compatibility with the 1.4 API
2217 svn_io_detect_mimetype(const char **mimetype,
2222 /** Examine up to @a len bytes of data in @a buf to determine if the
2223 * can be considered binary data, in which case return TRUE.
2224 * If the data can be considered plain-text data, return FALSE.
2226 * @since New in 1.7.
2229 svn_io_is_binary_data(const void *buf, apr_size_t len);
2232 /** Wrapper for apr_file_open(). @a fname is utf8-encoded.
2233 Always passed flag | APR_BINARY to apr. */
2235 svn_io_file_open(apr_file_t **new_file,
2238 apr_fileperms_t perm,
2242 /** Wrapper for apr_file_close(). */
2244 svn_io_file_close(apr_file_t *file,
2248 /** Wrapper for apr_file_getc(). */
2250 svn_io_file_getc(char *ch,
2255 /** Wrapper for apr_file_putc().
2259 svn_io_file_putc(char ch,
2264 /** Wrapper for apr_file_info_get(). */
2266 svn_io_file_info_get(apr_finfo_t *finfo,
2272 /** Set @a *filesize_p to the size of @a file. Use @a pool for temporary
2275 * @note Use svn_io_file_info_get() to get more information about
2278 * @since New in 1.10
2281 svn_io_file_size_get(svn_filesize_t *filesize_p, apr_file_t *file,
2284 /** Fetch the current offset of @a file into @a *offset_p. Use @a pool for
2285 * temporary allocations.
2287 * @since New in 1.10
2290 svn_io_file_get_offset(apr_off_t *offset_p,
2294 /** Wrapper for apr_file_read(). */
2296 svn_io_file_read(apr_file_t *file,
2302 /** Wrapper for apr_file_read_full().
2304 * If @a hit_eof is not NULL, EOF will be indicated there and no
2305 * svn_error_t error object will be created upon EOF.
2310 svn_io_file_read_full2(apr_file_t *file,
2313 apr_size_t *bytes_read,
2314 svn_boolean_t *hit_eof,
2318 /** Similar to svn_io_file_read_full2 with hit_eof being set
2321 * @deprecated Provided for backward compatibility with the 1.6 API
2325 svn_io_file_read_full(apr_file_t *file,
2328 apr_size_t *bytes_read,
2332 /** Wrapper for apr_file_seek(). */
2334 svn_io_file_seek(apr_file_t *file,
2335 apr_seek_where_t where,
2339 /** Set the file pointer of the #APR_BUFFERED @a file to @a offset. In
2340 * contrast to #svn_io_file_seek, this function will attempt to resize the
2341 * internal data buffer to @a block_size bytes and to read data aligned to
2342 * multiples of that value. The beginning of the block will be returned
2343 * in @a buffer_start, if that is not NULL.
2344 * Uses @a scratch_pool for temporary allocations.
2346 * @note Due to limitations of the APR API, the alignment may not be
2347 * successful. If you never use any other seek function on @a file,
2348 * however, you are virtually guaranteed to get at least 4kByte alignment
2351 * @note Calling this for non-buffered files is legal but inefficient.
2356 svn_io_file_aligned_seek(apr_file_t *file,
2357 apr_off_t block_size,
2358 apr_off_t *buffer_start,
2360 apr_pool_t *scratch_pool);
2362 /** Wrapper for apr_file_write(). */
2364 svn_io_file_write(apr_file_t *file,
2369 /** Wrapper for apr_file_flush().
2373 svn_io_file_flush(apr_file_t *file,
2374 apr_pool_t *scratch_pool);
2378 /** Wrapper for apr_file_write_full(). */
2380 svn_io_file_write_full(apr_file_t *file,
2383 apr_size_t *bytes_written,
2387 * Writes @a nbytes bytes from @a *buf to a temporary file inside the same
2388 * directory as @a *final_path. Then syncs the temporary file to disk and
2389 * closes the file. After this rename the temporary file to @a final_path,
2390 * possibly replacing an existing file.
2392 * If @a copy_perms_path is not NULL, copy the permissions applied on @a
2393 * @a copy_perms_path on the temporary file before renaming.
2395 * If @a flush_to_disk is non-zero, do not return until the node has
2396 * actually been written on the disk.
2398 * @note The flush to disk operation can be very expensive on systems
2399 * that implement flushing on all IO layers, like Windows. Please use
2400 * @a flush_to_disk flag only for critical data.
2402 * @since New in 1.10.
2405 svn_io_write_atomic2(const char *final_path,
2408 const char *copy_perms_path,
2409 svn_boolean_t flush_to_disk,
2410 apr_pool_t *scratch_pool);
2412 /** Similar to svn_io_write_atomic2(), but with @a flush_to_disk set
2415 * @since New in 1.9.
2417 * @deprecated Provided for backward compatibility with the 1.9 API
2421 svn_io_write_atomic(const char *final_path,
2424 const char* copy_perms_path,
2425 apr_pool_t *scratch_pool);
2428 * Open a unique file in @a dirpath, and write @a nbytes from @a buf to
2429 * the file before flushing it to disk and closing it. Return the name
2430 * of the newly created file in @a *tmp_path, allocated in @a pool.
2432 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
2433 * (Note that when using the system-provided temp directory, it may not
2434 * be possible to atomically rename the resulting file due to cross-device
2437 * The file will be deleted according to @a delete_when.
2439 * @since New in 1.6.
2442 svn_io_write_unique(const char **tmp_path,
2443 const char *dirpath,
2446 svn_io_file_del_t delete_when,
2449 /** Wrapper for apr_file_trunc().
2450 * @since New in 1.6. */
2452 svn_io_file_trunc(apr_file_t *file,
2457 /** Wrapper for apr_stat(). @a fname is utf8-encoded. */
2459 svn_io_stat(apr_finfo_t *finfo,
2465 /** Rename and/or move the node (not necessarily a regular file) at
2466 * @a from_path to a new path @a to_path within the same filesystem.
2467 * In some cases, an existing node at @a to_path will be overwritten.
2469 * @a from_path and @a to_path are utf8-encoded. If @a flush_to_disk
2470 * is non-zero, do not return until the node has actually been moved on
2473 * @note The flush to disk operation can be very expensive on systems
2474 * that implement flushing on all IO layers, like Windows. Please use
2475 * @a flush_to_disk flag only for critical data.
2477 * @since New in 1.10.
2480 svn_io_file_rename2(const char *from_path, const char *to_path,
2481 svn_boolean_t flush_to_disk, apr_pool_t *pool);
2483 /** Similar to svn_io_file_rename2(), but with @a flush_to_disk set
2486 * @deprecated Provided for backward compatibility with the 1.9 API
2490 svn_io_file_rename(const char *from_path,
2491 const char *to_path,
2495 /** Move the file from @a from_path to @a to_path, even across device
2496 * boundaries. Overwrite @a to_path if it exists.
2498 * @note This function is different from svn_io_file_rename in that the
2499 * latter fails in the 'across device boundaries' case.
2501 * @since New in 1.3.
2504 svn_io_file_move(const char *from_path,
2505 const char *to_path,
2509 /** Wrapper for apr_dir_make(). @a path is utf8-encoded. */
2511 svn_io_dir_make(const char *path,
2512 apr_fileperms_t perm,
2515 /** Same as svn_io_dir_make(), but sets the hidden attribute on the
2516 directory on systems that support it. */
2518 svn_io_dir_make_hidden(const char *path,
2519 apr_fileperms_t perm,
2523 * Same as svn_io_dir_make(), but attempts to set the sgid on the
2524 * directory on systems that support it. Does not return an error if
2525 * the attempt to set the sgid bit fails. On Unix filesystems,
2526 * setting the sgid bit on a directory ensures that files and
2527 * subdirectories created within inherit group ownership from the
2528 * parent instead of from the primary gid.
2530 * @since New in 1.1.
2533 svn_io_dir_make_sgid(const char *path,
2534 apr_fileperms_t perm,
2537 /** Wrapper for apr_dir_open(). @a dirname is utf8-encoded. */
2539 svn_io_dir_open(apr_dir_t **new_dir,
2540 const char *dirname,
2543 /** Wrapper for apr_dir_close().
2545 * @since New in 1.7.
2548 svn_io_dir_close(apr_dir_t *thedir);
2550 /** Wrapper for apr_dir_remove(). @a dirname is utf8-encoded.
2551 * @note This function has this name to avoid confusion with
2552 * svn_io_remove_dir2(), which is recursive.
2555 svn_io_dir_remove_nonrecursive(const char *dirname,
2559 /** Wrapper for apr_dir_read(). Ensures that @a finfo->name is
2560 * utf8-encoded, which means allocating @a finfo->name in @a pool,
2561 * which may or may not be the same as @a finfo's pool. Use @a pool
2562 * for error allocation as well.
2565 svn_io_dir_read(apr_finfo_t *finfo,
2570 /** Wrapper for apr_file_name_get(). @a *filename is utf8-encoded.
2572 * @note The file name may be NULL.
2574 * @since New in 1.7. */
2576 svn_io_file_name_get(const char **filename,
2582 /** Version/format files.
2584 * @defgroup svn_io_format_files Version/format files
2588 /** Set @a *version to the integer that starts the file at @a path. If the
2589 * file does not begin with a series of digits followed by a newline,
2590 * return the error #SVN_ERR_BAD_VERSION_FILE_FORMAT. Use @a pool for
2594 svn_io_read_version_file(int *version,
2598 /** Create (or overwrite) the file at @a path with new contents,
2599 * formatted as a non-negative integer @a version followed by a single
2600 * newline. On successful completion the file will be read-only. Use
2601 * @a pool for all allocations.
2604 svn_io_write_version_file(const char *path,
2608 /** Read a line of text from a file, up to a specified length.
2610 * Allocate @a *stringbuf in @a result_pool, and read into it one line
2611 * from @a file. Reading stops either after a line-terminator was found
2612 * or after @a max_len bytes have been read.
2614 * If end-of-file is reached or @a max_len bytes have been read, and @a eof
2615 * is not NULL, then set @a *eof to @c TRUE.
2617 * The line-terminator is not stored in @a *stringbuf.
2618 * The line-terminator is detected automatically and stored in @a *eol
2619 * if @a eol is not NULL. If EOF is reached and @a file does not end
2620 * with a newline character, and @a eol is not NULL, @ *eol is set to NULL.
2622 * @a scratch_pool is used for temporary allocations.
2624 * Hint: To read all data until a line-terminator is hit, pass APR_SIZE_MAX
2627 * @since New in 1.8.
2630 svn_io_file_readline(apr_file_t *file,
2631 svn_stringbuf_t **stringbuf,
2635 apr_pool_t *result_pool,
2636 apr_pool_t *scratch_pool);
2642 #endif /* __cplusplus */
2644 #endif /* SVN_IO_H */