Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_io.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Copyright (c) 2000-2008 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_io.h
19  * @brief General file I/O for Subversion
20  */
21 
22 /* ==================================================================== */
23 
24 
25 #ifndef SVN_IO_H
26 #define SVN_IO_H
27 
28 #include <apr.h>
29 #include <apr_pools.h>
30 #include <apr_time.h>
31 #include <apr_hash.h>
32 #include <apr_tables.h>
33 #include <apr_file_io.h>
34 #include <apr_file_info.h>
35 #include <apr_thread_proc.h> /* for apr_proc_t, apr_exit_why_e */
36 
37 #include "svn_types.h"
38 #include "svn_string.h"
39 #include "svn_checksum.h"
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif /* __cplusplus */
44 
45 
46 
47 /** Used as an argument when creating temporary files to indicate
48  * when a file should be removed.
49  *
50  * @since New in 1.4.
51  *
52  * Not specifying any of these means no removal at all. */
53 typedef enum svn_io_file_del_t
54 {
55  /** No deletion ever */
57  /** Remove when the file is closed */
59  /** Remove when the associated pool is cleared */
62 
63 
64 
65 /** Represents the kind and special status of a directory entry.
66  *
67  * @since New in 1.3.
68  */
69 typedef struct svn_io_dirent_t {
70  /** The kind of this entry. */
72  /** If @c kind is @c svn_node_file, whether this entry is a special file;
73  * else FALSE.
74  *
75  * @see svn_io_check_special_path().
76  */
79 
80 /** Determine the @a kind of @a path. @a path should be UTF-8 encoded.
81  *
82  * If @a path is a file, set @a *kind to @c svn_node_file.
83  *
84  * If @a path is a directory, set @a *kind to @c svn_node_dir.
85  *
86  * If @a path does not exist, set @a *kind to @c svn_node_none.
87  *
88  * If @a path exists but is none of the above, set @a *kind to @c
89  * svn_node_unknown.
90  *
91  * If @a path is not a valid pathname, set @a *kind to #svn_node_none. If
92  * unable to determine @a path's kind for any other reason, return an error,
93  * with @a *kind's value undefined.
94  *
95  * Use @a pool for temporary allocations.
96  *
97  * @see svn_node_kind_t
98  */
100 svn_io_check_path(const char *path,
101  svn_node_kind_t *kind,
102  apr_pool_t *pool);
103 
104 /**
105  * Like svn_io_check_path(), but also set *is_special to @c TRUE if
106  * the path is not a normal file.
107  *
108  * @since New in 1.1.
109  */
110 svn_error_t *
111 svn_io_check_special_path(const char *path,
112  svn_node_kind_t *kind,
113  svn_boolean_t *is_special,
114  apr_pool_t *pool);
115 
116 /** Like svn_io_check_path(), but resolve symlinks. This returns the
117  same varieties of @a kind as svn_io_check_path(). */
118 svn_error_t *
119 svn_io_check_resolved_path(const char *path,
120  svn_node_kind_t *kind,
121  apr_pool_t *pool);
122 
123 
124 /** Open a new file (for reading and writing) with a unique name based on
125  * utf-8 encoded @a filename, in the directory @a dirpath. The file handle is
126  * returned in @a *file, and the name, which ends with @a suffix, is returned
127  * in @a *unique_name, also utf8-encoded. Either @a file or @a unique_name
128  * may be @c NULL.
129  *
130  * If @a delete_when is @c svn_io_file_del_on_close, then the @c APR_DELONCLOSE
131  * flag will be used when opening the file. The @c APR_BUFFERED flag will
132  * always be used.
133  *
134  * The first attempt will just append @a suffix. If the result is not
135  * a unique name, then subsequent attempts will append a dot,
136  * followed by an iteration number ("2", then "3", and so on),
137  * followed by the suffix. For example, successive calls to
138  *
139  * svn_io_open_uniquely_named(&f, &u, "tests/t1/A/D/G", "pi", ".tmp", ...)
140  *
141  * will open
142  *
143  * tests/t1/A/D/G/pi.tmp
144  * tests/t1/A/D/G/pi.2.tmp
145  * tests/t1/A/D/G/pi.3.tmp
146  * tests/t1/A/D/G/pi.4.tmp
147  * tests/t1/A/D/G/pi.5.tmp
148  * ...
149  *
150  * Assuming @a suffix is non-empty, @a *unique_name will never be exactly
151  * the same as @a filename, even if @a filename does not exist.
152  *
153  * If @a dirpath is NULL, then the directory returned by svn_io_temp_dir()
154  * will be used.
155  *
156  * If @a filename is NULL, then "tempfile" will be used.
157  *
158  * If @a suffix is NULL, then ".tmp" will be used.
159  *
160  * Allocates @a *file and @a *unique_name in @a result_pool. All
161  * intermediate allocations will be performed in @a scratch_pool.
162  *
163  * If no unique name can be found, @c SVN_ERR_IO_UNIQUE_NAMES_EXHAUSTED is
164  * the error returned.
165  *
166  * Claim of Historical Inevitability: this function was written
167  * because
168  *
169  * - tmpnam() is not thread-safe.
170  * - tempname() tries standard system tmp areas first.
171  *
172  * @since New in 1.6
173  */
174 svn_error_t *
175 svn_io_open_uniquely_named(apr_file_t **file,
176  const char **unique_name,
177  const char *dirpath,
178  const char *filename,
179  const char *suffix,
180  svn_io_file_del_t delete_when,
181  apr_pool_t *result_pool,
182  apr_pool_t *scratch_pool);
183 
184 
185 /** Create a writable file in the directory @a dirpath. The file will have
186  * an arbitrary and unique name, and the full path will be returned in
187  * @a temp_path. The file will be returned in @a file. Both will be
188  * allocated from @a result_pool.
189  *
190  * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
191  * (Note that when using the system-provided temp directory, it may not
192  * be possibly to atomically rename the resulting file due to cross-device
193  * issues.)
194  *
195  * The file will be deleted according to @a delete_when.
196  *
197  * Temporary allocations will be performed in @a scratch_pool.
198  *
199  * @since New in 1.6
200  * @see svn_stream_open_unique()
201  */
202 svn_error_t *
203 svn_io_open_unique_file3(apr_file_t **file,
204  const char **temp_path,
205  const char *dirpath,
206  svn_io_file_del_t delete_when,
207  apr_pool_t *result_pool,
208  apr_pool_t *scratch_pool);
209 
210 
211 /** Like svn_io_open_uniquely_named(), but takes a joined dirpath and
212  * filename, and a single pool.
213  *
214  * @since New in 1.4
215  *
216  * @deprecated Provided for backward compatibility with the 1.5 API
217  */
219 svn_error_t *
220 svn_io_open_unique_file2(apr_file_t **f,
221  const char **unique_name_p,
222  const char *path,
223  const char *suffix,
224  svn_io_file_del_t delete_when,
225  apr_pool_t *pool);
226 
227 /** Like svn_io_open_unique_file2, but can't delete on pool cleanup.
228  *
229  * @deprecated Provided for backward compatibility with the 1.0 API
230  *
231  * @note In 1.4 the API was extended to require either @a f or
232  * @a unique_name_p (the other can be NULL). Before that, both were
233  * required.
234  */
236 svn_error_t *
237 svn_io_open_unique_file(apr_file_t **f,
238  const char **unique_name_p,
239  const char *path,
240  const char *suffix,
241  svn_boolean_t delete_on_close,
242  apr_pool_t *pool);
243 
244 
245 /**
246  * Like svn_io_open_unique_file(), except that instead of creating a
247  * file, a symlink is generated that references the path @a dest.
248  *
249  * @since New in 1.1.
250  */
251 svn_error_t *
252 svn_io_create_unique_link(const char **unique_name_p,
253  const char *path,
254  const char *dest,
255  const char *suffix,
256  apr_pool_t *pool);
257 
258 
259 /**
260  * Set @a *dest to the path that the symlink at @a path references.
261  * Allocate the string from @a pool.
262  *
263  * @since New in 1.1.
264  */
265 svn_error_t *
267  const char *path,
268  apr_pool_t *pool);
269 
270 
271 /** Set @a *dir to a directory path (allocated in @a pool) deemed
272  * usable for the creation of temporary files and subdirectories.
273  */
274 svn_error_t *
275 svn_io_temp_dir(const char **dir,
276  apr_pool_t *pool);
277 
278 
279 /** Copy @a src to @a dst atomically, in a "byte-for-byte" manner.
280  * Overwrite @a dst if it exists, else create it. Both @a src and @a dst
281  * are utf8-encoded filenames. If @a copy_perms is TRUE, set @a dst's
282  * permissions to match those of @a src.
283  */
284 svn_error_t *
285 svn_io_copy_file(const char *src,
286  const char *dst,
287  svn_boolean_t copy_perms,
288  apr_pool_t *pool);
289 
290 
291 /** Copy permission flags from @a src onto the file at @a dst. Both
292  * filenames are utf8-encoded filenames.
293  */
294 svn_error_t *
295 svn_io_copy_perms(const char *src,
296  const char *dst,
297  apr_pool_t *pool);
298 
299 
300 /**
301  * Copy symbolic link @a src to @a dst atomically. Overwrite @a dst
302  * if it exists, else create it. Both @a src and @a dst are
303  * utf8-encoded filenames. After copying, the @a dst link will point
304  * to the same thing @a src does.
305  *
306  * @since New in 1.1.
307  */
308 svn_error_t *
309 svn_io_copy_link(const char *src,
310  const char *dst,
311  apr_pool_t *pool);
312 
313 
314 /** Recursively copy directory @a src into @a dst_parent, as a new entry named
315  * @a dst_basename. If @a dst_basename already exists in @a dst_parent,
316  * return error. @a copy_perms will be passed through to svn_io_copy_file()
317  * when any files are copied. @a src, @a dst_parent, and @a dst_basename are
318  * all utf8-encoded.
319  *
320  * If @a cancel_func is non-NULL, invoke it with @a cancel_baton at
321  * various points during the operation. If it returns any error
322  * (typically @c SVN_ERR_CANCELLED), return that error immediately.
323  */
324 svn_error_t *
325 svn_io_copy_dir_recursively(const char *src,
326  const char *dst_parent,
327  const char *dst_basename,
328  svn_boolean_t copy_perms,
329  svn_cancel_func_t cancel_func,
330  void *cancel_baton,
331  apr_pool_t *pool);
332 
333 
334 /** Create directory @a path on the file system, creating intermediate
335  * directories as required, like <tt>mkdir -p</tt>. Report no error if @a
336  * path already exists. @a path is utf8-encoded.
337  *
338  * This is essentially a wrapper for apr_dir_make_recursive(), passing
339  * @c APR_OS_DEFAULT as the permissions.
340  */
341 svn_error_t *
342 svn_io_make_dir_recursively(const char *path,
343  apr_pool_t *pool);
344 
345 
346 /** Set @a *is_empty_p to @c TRUE if directory @a path is empty, else to
347  * @c FALSE if it is not empty. @a path must be a directory, and is
348  * utf8-encoded. Use @a pool for temporary allocation.
349  */
350 svn_error_t *
351 svn_io_dir_empty(svn_boolean_t *is_empty_p,
352  const char *path,
353  apr_pool_t *pool);
354 
355 
356 /** Append @a src to @a dst. @a dst will be appended to if it exists, else it
357  * will be created. Both @a src and @a dst are utf8-encoded.
358  */
359 svn_error_t *
360 svn_io_append_file(const char *src,
361  const char *dst,
362  apr_pool_t *pool);
363 
364 
365 /** Make a file as read-only as the operating system allows.
366  * @a path is the utf8-encoded path to the file. If @a ignore_enoent is
367  * @c TRUE, don't fail if the target file doesn't exist.
368  *
369  * If @a path is a symlink, do nothing.
370  *
371  * @note If @a path is a directory, act on it as though it were a
372  * file, as described above, but note that you probably don't want to
373  * call this function on directories. We have left it effective on
374  * directories for compatibility reasons, but as its name implies, it
375  * should be used only for files.
376  */
377 svn_error_t *
378 svn_io_set_file_read_only(const char *path,
379  svn_boolean_t ignore_enoent,
380  apr_pool_t *pool);
381 
382 
383 /** Make a file as writable as the operating system allows.
384  * @a path is the utf8-encoded path to the file. If @a ignore_enoent is
385  * @c TRUE, don't fail if the target file doesn't exist.
386  * @warning On Unix this function will do the equivalent of chmod a+w path.
387  * If this is not what you want you should not use this function, but rather
388  * use apr_file_perms_set().
389  *
390  * If @a path is a symlink, do nothing.
391  *
392  * @note If @a path is a directory, act on it as though it were a
393  * file, as described above, but note that you probably don't want to
394  * call this function on directories. We have left it effective on
395  * directories for compatibility reasons, but as its name implies, it
396  * should be used only for files.
397  */
398 svn_error_t *
399 svn_io_set_file_read_write(const char *path,
400  svn_boolean_t ignore_enoent,
401  apr_pool_t *pool);
402 
403 
404 /** Similar to svn_io_set_file_read_* functions.
405  * Change the read-write permissions of a file.
406  * @since New in 1.1.
407  *
408  * When making @a path read-write on operating systems with unix style
409  * permissions, set the permissions on @a path to the permissions that
410  * are set when a new file is created (effectively honoring the user's
411  * umask).
412  *
413  * When making the file read-only on operating systems with unix style
414  * permissions, remove all write permissions.
415  *
416  * On other operating systems, toggle the file's "writability" as much as
417  * the operating system allows.
418  *
419  * @a path is the utf8-encoded path to the file. If @a enable_write
420  * is @c TRUE, then make the file read-write. If @c FALSE, make it
421  * read-only. If @a ignore_enoent is @c TRUE, don't fail if the target
422  * file doesn't exist.
423  *
424  * @deprecated Provided for backward compatibility with the 1.3 API.
425  */
427 svn_error_t *
428 svn_io_set_file_read_write_carefully(const char *path,
429  svn_boolean_t enable_write,
430  svn_boolean_t ignore_enoent,
431  apr_pool_t *pool);
432 
433 /** Set @a path's "executability" (but do nothing if it is a symlink).
434  *
435  * @a path is the utf8-encoded path to the file. If @a executable
436  * is @c TRUE, then make the file executable. If @c FALSE, make it
437  * non-executable. If @a ignore_enoent is @c TRUE, don't fail if the target
438  * file doesn't exist.
439  *
440  * When making the file executable on operating systems with unix style
441  * permissions, never add an execute permission where there is not
442  * already a read permission: that is, only make the file executable
443  * for the user, group or world if the corresponding read permission
444  * is already set for user, group or world.
445  *
446  * When making the file non-executable on operating systems with unix style
447  * permissions, remove all execute permissions.
448  *
449  * On other operating systems, toggle the file's "executability" as much as
450  * the operating system allows.
451  *
452  * @note If @a path is a directory, act on it as though it were a
453  * file, as described above, but note that you probably don't want to
454  * call this function on directories. We have left it effective on
455  * directories for compatibility reasons, but as its name implies, it
456  * should be used only for files.
457  */
458 svn_error_t *
459 svn_io_set_file_executable(const char *path,
460  svn_boolean_t executable,
461  svn_boolean_t ignore_enoent,
462  apr_pool_t *pool);
463 
464 /** Determine whether a file is executable by the current user.
465  * Set @a *executable to @c TRUE if the file @a path is executable by the
466  * current user, otherwise set it to @c FALSE.
467  *
468  * On Windows and on platforms without userids, always returns @c FALSE.
469  */
470 svn_error_t *
472  const char *path,
473  apr_pool_t *pool);
474 
475 
476 /** Read a line from @a file into @a buf, but not exceeding @a *limit bytes.
477  * Does not include newline, instead '\\0' is put there.
478  * Length (as in strlen) is returned in @a *limit.
479  * @a buf should be pre-allocated.
480  * @a file should be already opened.
481  *
482  * When the file is out of lines, @c APR_EOF will be returned.
483  */
484 svn_error_t *
485 svn_io_read_length_line(apr_file_t *file,
486  char *buf,
487  apr_size_t *limit,
488  apr_pool_t *pool);
489 
490 
491 /** Set @a *apr_time to the time of last modification of the contents of the
492  * file @a path. @a path is utf8-encoded.
493  *
494  * @note This is the APR mtime which corresponds to the traditional mtime
495  * on Unix, and the last write time on Windows.
496  */
497 svn_error_t *
498 svn_io_file_affected_time(apr_time_t *apr_time,
499  const char *path,
500  apr_pool_t *pool);
501 
502 /** Set the timestamp of file @a path to @a apr_time. @a path is
503  * utf8-encoded.
504  *
505  * @note This is the APR mtime which corresponds to the traditional mtime
506  * on Unix, and the last write time on Windows.
507  */
508 svn_error_t *
509 svn_io_set_file_affected_time(apr_time_t apr_time,
510  const char *path,
511  apr_pool_t *pool);
512 
513 /** Sleep to ensure that any files modified after we exit have a different
514  * timestamp than the one we recorded. If @a path is not NULL, check if we
515  * can determine how long we should wait for a new timestamp on the filesystem
516  * containing @a path, an existing file or directory. If @a path is NULL or we
517  * can't determine the timestamp resolution, sleep until the next second.
518  *
519  * Use @a pool for any necessary allocations. @a pool can be null if @a path
520  * is NULL.
521  *
522  * Errors while retrieving the timestamp resolution will result in sleeping
523  * to the next second, to keep the working copy stable in error conditions.
524  *
525  * @since New in 1.6.
526  */
527 void
528 svn_io_sleep_for_timestamps(const char *path, apr_pool_t *pool);
529 
530 /** Set @a *different_p to non-zero if @a file1 and @a file2 have different
531  * sizes, else set to zero. Both @a file1 and @a file2 are utf8-encoded.
532  *
533  * Setting @a *different_p to zero does not mean the files definitely
534  * have the same size, it merely means that the sizes are not
535  * definitely different. That is, if the size of one or both files
536  * cannot be determined, then the sizes are not known to be different,
537  * so @a *different_p is set to 0.
538  */
539 svn_error_t *
541  const char *file1,
542  const char *file2,
543  apr_pool_t *pool);
544 
545 
546 /** Return in @a *checksum the checksum of type @a kind of @a file
547  * Use @a pool for temporary allocations and to allocate @a *checksum.
548  *
549  * @since New in 1.6.
550  */
551 svn_error_t *
553  const char *file,
554  svn_checksum_kind_t kind,
555  apr_pool_t *pool);
556 
557 
558 /** Put the md5 checksum of @a file into @a digest.
559  * @a digest points to @c APR_MD5_DIGESTSIZE bytes of storage.
560  * Use @a pool only for temporary allocations.
561  *
562  * @deprecated Provided for backward compatibility with the 1.5 API.
563  */
565 svn_error_t *
566 svn_io_file_checksum(unsigned char digest[],
567  const char *file,
568  apr_pool_t *pool);
569 
570 
571 /** Set @a *same to TRUE if @a file1 and @a file2 have the same
572  * contents, else set it to FALSE. Use @a pool for temporary allocations.
573  */
574 svn_error_t *
576  const char *file1,
577  const char *file2,
578  apr_pool_t *pool);
579 
580 /** Create file at utf8-encoded @a file with contents @a contents.
581  * @a file must not already exist.
582  * Use @a pool for memory allocations.
583  */
584 svn_error_t *
585 svn_io_file_create(const char *file,
586  const char *contents,
587  apr_pool_t *pool);
588 
589 /**
590  * Lock file at @a lock_file. If @a exclusive is TRUE,
591  * obtain exclusive lock, otherwise obtain shared lock.
592  * Lock will be automatically released when @a pool is cleared or destroyed.
593  * Use @a pool for memory allocations.
594  *
595  * @deprecated Provided for backward compatibility with the 1.0 API.
596  */
598 svn_error_t *
599 svn_io_file_lock(const char *lock_file,
600  svn_boolean_t exclusive,
601  apr_pool_t *pool);
602 
603 /**
604  * Lock file at @a lock_file. If @a exclusive is TRUE,
605  * obtain exclusive lock, otherwise obtain shared lock.
606  *
607  * If @a nonblocking is TRUE, do not wait for the lock if it
608  * is not available: throw an error instead.
609  *
610  * Lock will be automatically released when @a pool is cleared or destroyed.
611  * Use @a pool for memory allocations.
612  *
613  * @since New in 1.1.
614  */
615 svn_error_t *
616 svn_io_file_lock2(const char *lock_file,
617  svn_boolean_t exclusive,
618  svn_boolean_t nonblocking,
619  apr_pool_t *pool);
620 /**
621  * Flush any unwritten data from @a file to disk. Use @a pool for
622  * memory allocations.
623  *
624  * @since New in 1.1.
625  */
626 svn_error_t *
627 svn_io_file_flush_to_disk(apr_file_t *file,
628  apr_pool_t *pool);
629 
630 /** Copy file @a file from location @a src_path to location @a dest_path.
631  * Use @a pool for memory allocations.
632  */
633 svn_error_t *
634 svn_io_dir_file_copy(const char *src_path,
635  const char *dest_path,
636  const char *file,
637  apr_pool_t *pool);
638 
639 
640 /** Generic byte-streams
641  *
642  * @defgroup svn_io_byte_streams Generic byte streams
643  * @{
644  */
645 
646 /** An abstract stream of bytes--either incoming or outgoing or both.
647  *
648  * The creator of a stream sets functions to handle read and write.
649  * Both of these handlers accept a baton whose value is determined at
650  * stream creation time; this baton can point to a structure
651  * containing data associated with the stream. If a caller attempts
652  * to invoke a handler which has not been set, it will generate a
653  * runtime assertion failure. The creator can also set a handler for
654  * close requests so that it can flush buffered data or whatever;
655  * if a close handler is not specified, a close request on the stream
656  * will simply be ignored. Note that svn_stream_close() does not
657  * deallocate the memory used to allocate the stream structure; free
658  * the pool you created the stream in to free that memory.
659  *
660  * The read and write handlers accept length arguments via pointer.
661  * On entry to the handler, the pointed-to value should be the amount
662  * of data which can be read or the amount of data to write. When the
663  * handler returns, the value is reset to the amount of data actually
664  * read or written. Handlers are obliged to complete a read or write
665  * to the maximum extent possible; thus, a short read with no
666  * associated error implies the end of the input stream, and a short
667  * write should never occur without an associated error.
668  */
669 typedef struct svn_stream_t svn_stream_t;
670 
671 
672 
673 /** Read handler function for a generic stream. @see svn_stream_t. */
674 typedef svn_error_t *(*svn_read_fn_t)(void *baton,
675  char *buffer,
676  apr_size_t *len);
677 
678 /** Write handler function for a generic stream. @see svn_stream_t. */
679 typedef svn_error_t *(*svn_write_fn_t)(void *baton,
680  const char *data,
681  apr_size_t *len);
682 
683 /** Close handler function for a generic stream. @see svn_stream_t. */
684 typedef svn_error_t *(*svn_close_fn_t)(void *baton);
685 
686 
687 /** Create a generic stream. @see svn_stream_t. */
688 svn_stream_t *
689 svn_stream_create(void *baton,
690  apr_pool_t *pool);
691 
692 /** Set @a stream's baton to @a baton */
693 void
695  void *baton);
696 
697 /** Set @a stream's read function to @a read_fn */
698 void
700  svn_read_fn_t read_fn);
701 
702 /** Set @a stream's write function to @a write_fn */
703 void
705  svn_write_fn_t write_fn);
706 
707 /** Set @a stream's close function to @a close_fn */
708 void
710  svn_close_fn_t close_fn);
711 
712 
713 /** Create a stream that is empty for reading and infinite for writing. */
714 svn_stream_t *
715 svn_stream_empty(apr_pool_t *pool);
716 
717 /** Return a stream allocated in @a pool which forwards all requests
718  * to @a stream. Destruction is explicitly excluded from forwarding.
719  *
720  * @see notes/destruction-of-stacked-resources
721  *
722  * @since New in 1.4.
723  */
724 svn_stream_t *
726  apr_pool_t *pool);
727 
728 
729 /** Create a stream to read the file at @a path. It will be opened using
730  * the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the perms.
731  * If you'd like to use different values, then open the file yourself, and
732  * use the svn_stream_from_aprfile2() interface.
733  *
734  * The stream will be returned in @a stream, and allocated from @a result_pool.
735  * Temporary allocations will be performed in @a scratch_pool.
736  *
737  * @since New in 1.6
738  */
739 svn_error_t *
741  const char *path,
742  apr_pool_t *result_pool,
743  apr_pool_t *scratch_pool);
744 
745 
746 /** Create a stream to write a file at @a path. The file will be *created*
747  * using the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the
748  * perms. The file will be created "exclusively", so if it already exists,
749  * then an error will be thrown. If you'd like to use different values, or
750  * open an existing file, then open the file yourself, and use the
751  * svn_stream_from_aprfile2() interface.
752  *
753  * The stream will be returned in @a stream, and allocated from @a result_pool.
754  * Temporary allocations will be performed in @a scratch_pool.
755  *
756  * @since New in 1.6
757  */
758 svn_error_t *
760  const char *path,
761  apr_pool_t *result_pool,
762  apr_pool_t *scratch_pool);
763 
764 
765 /** Create a writable stream to a file in the directory @a dirpath.
766  * The file will have an arbitrary and unique name, and the full path
767  * will be returned in @a temp_path. The stream will be returned in
768  * @a stream. Both will be allocated from @a result_pool.
769  *
770  * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
771  * (Note that when using the system-provided temp directory, it may not
772  * be possibly to atomically rename the resulting file due to cross-device
773  * issues.)
774  *
775  * The file will be deleted according to @a delete_when.
776  *
777  * Temporary allocations will be performed in @a scratch_pool.
778  *
779  * @since New in 1.6
780  * @see svn_io_open_unique_file3()
781  */
782 svn_error_t *
784  const char **temp_path,
785  const char *dirpath,
786  svn_io_file_del_t delete_when,
787  apr_pool_t *result_pool,
788  apr_pool_t *scratch_pool);
789 
790 
791 /** Create a stream from an APR file. For convenience, if @a file is
792  * @c NULL, an empty stream created by svn_stream_empty() is returned.
793  *
794  * This function should normally be called with @a disown set to FALSE,
795  * in which case closing the stream will also close the underlying file.
796  *
797  * If @a disown is TRUE, the stream will disown the underlying file,
798  * meaning that svn_stream_close() will not close the file.
799  *
800  * @since New in 1.4.
801  */
802 svn_stream_t *
803 svn_stream_from_aprfile2(apr_file_t *file,
804  svn_boolean_t disown,
805  apr_pool_t *pool);
806 
807 /** Similar to svn_stream_from_aprfile2(), except that the file will
808  * always be disowned.
809  *
810  * @note The stream returned is not considered to "own" the underlying
811  * file, meaning that svn_stream_close() on the stream will not
812  * close the file.
813  *
814  * @deprecated Provided for backward compatibility with the 1.3 API.
815  */
817 svn_stream_t *
818 svn_stream_from_aprfile(apr_file_t *file,
819  apr_pool_t *pool);
820 
821 /** Set @a *out to a generic stream connected to stdout, allocated in
822  * @a pool. The stream and its underlying APR handle will be closed
823  * when @a pool is cleared or destroyed.
824  */
825 svn_error_t *
827  apr_pool_t *pool);
828 
829 /** Return a generic stream connected to stringbuf @a str. Allocate the
830  * stream in @a pool.
831  */
832 svn_stream_t *
834  apr_pool_t *pool);
835 
836 /** Return a generic read-only stream connected to string @a str.
837  * Allocate the stream in @a pool.
838  */
839 svn_stream_t *
841  apr_pool_t *pool);
842 
843 /** Return a stream that decompresses all data read and compresses all
844  * data written. The stream @a stream is used to read and write all
845  * compressed data. All compression data structures are allocated on
846  * @a pool. If compression support is not compiled in then
847  * svn_stream_compressed() returns @a stream unmodified. Make sure you
848  * call svn_stream_close() on the stream returned by this function,
849  * so that all data are flushed and cleaned up.
850  *
851  * @note From 1.4, compression support is always compiled in.
852  */
853 svn_stream_t *
855  apr_pool_t *pool);
856 
857 /** Return a stream that calculates checksums for all data read
858  * and written. The stream @a stream is used to read and write all data.
859  * The stream and the resulting digests are allocated in @a pool.
860  *
861  * When the stream is closed, @a *read_checksum and @a *write_checksum
862  * are set to point to the resulting checksums, of type @a read_checksum_kind
863  * and @a write_checksum_kind, respectively.
864  *
865  * Both @a read_checksum and @a write_checksum can be @c NULL, in which case
866  * the respective checksum isn't calculated.
867  *
868  * If @a read_all is TRUE, make sure that all data available on @a
869  * stream is read (and checksummed) when the stream is closed.
870  *
871  * Read and write operations can be mixed without interfering.
872  *
873  * The @a stream passed into this function is closed when the created
874  * stream is closed.
875  *
876  * @since New in 1.6.
877  */
878 svn_stream_t *
880  svn_checksum_t **read_checksum,
881  svn_checksum_t **write_checksum,
882  svn_checksum_kind_t checksum_kind,
883  svn_boolean_t read_all,
884  apr_pool_t *pool);
885 
886 /**
887  * Similar to svn_stream_checksummed2(), but always returning the MD5
888  * checksum in @a read_digest and @a write_digest.
889  *
890  * @since New in 1.4.
891  * @deprecated Provided for backward compatibility with the 1.5 API.
892  */
894 svn_stream_t *
896  const unsigned char **read_digest,
897  const unsigned char **write_digest,
898  svn_boolean_t read_all,
899  apr_pool_t *pool);
900 
901 /** Read from a generic stream. @see svn_stream_t. */
902 svn_error_t *
904  char *buffer,
905  apr_size_t *len);
906 
907 /** Write to a generic stream. @see svn_stream_t. */
908 svn_error_t *
910  const char *data,
911  apr_size_t *len);
912 
913 /** Close a generic stream. @see svn_stream_t. */
914 svn_error_t *
916 
917 
918 /** Write to @a stream using a printf-style @a fmt specifier, passed through
919  * apr_psprintf() using memory from @a pool.
920  */
921 svn_error_t *
923  apr_pool_t *pool,
924  const char *fmt,
925  ...)
926  __attribute__((format(printf, 3, 4)));
927 
928 /** Write to @a stream using a printf-style @a fmt specifier, passed through
929  * apr_psprintf() using memory from @a pool. The resulting string
930  * will be translated to @a encoding before it is sent to @a stream.
931  *
932  * @note Use @c APR_LOCALE_CHARSET to translate to the encoding of the
933  * current locale.
934  *
935  * @since New in 1.3.
936  */
937 svn_error_t *
939  const char *encoding,
940  apr_pool_t *pool,
941  const char *fmt,
942  ...)
943  __attribute__((format(printf, 4, 5)));
944 
945 /** Allocate @a *stringbuf in @a pool, and read into it one line (terminated
946  * by @a eol) from @a stream. The line-terminator is read from the stream,
947  * but is not added to the end of the stringbuf. Instead, the stringbuf
948  * ends with a usual '\\0'.
949  *
950  * If @a stream runs out of bytes before encountering a line-terminator,
951  * then set @a *eof to @c TRUE, otherwise set @a *eof to FALSE.
952  */
953 svn_error_t *
955  svn_stringbuf_t **stringbuf,
956  const char *eol,
957  svn_boolean_t *eof,
958  apr_pool_t *pool);
959 
960 
961 /**
962  * Read the contents of the readable stream @a from and write them to the
963  * writable stream @a to calling @a cancel_func before copying each chunk.
964  *
965  * @a cancel_func may be @c NULL.
966  *
967  * @note both @a from and @a to will be closed upon successful completion of
968  * the copy (but an error may still be returned, based on trying to close
969  * the two streams). If the closure is not desired, then you can use
970  * svn_stream_disown() to protect either or both of the streams from
971  * being closed.
972  * ### TODO: should close the streams ALWAYS, even on error exit
973  *
974  * @since New in 1.6.
975  */
976 svn_error_t *
978  svn_stream_t *to,
979  svn_cancel_func_t cancel_func,
980  void *cancel_baton,
981  apr_pool_t *pool);
982 
983 /**
984  * Same as svn_stream_copy3() but the streams are not closed.
985  *
986  * @since New in 1.5.
987  * @deprecated Provided for backward compatibility with the 1.5 API.
988  */
990 svn_error_t *
992  svn_stream_t *to,
993  svn_cancel_func_t cancel_func,
994  void *cancel_baton,
995  apr_pool_t *pool);
996 
997 /**
998  * Same as svn_stream_copy3(), but without the cancellation function
999  * or stream closing.
1000  *
1001  * @since New in 1.1.
1002  * @deprecated Provided for backward compatibility with the 1.4 API.
1003  */
1005 svn_error_t *
1007  svn_stream_t *to,
1008  apr_pool_t *pool);
1009 
1010 
1011 /** Set @a *same to TRUE if @a stream1 and @a stream2 have the same
1012  * contents, else set it to FALSE. Use @a pool for temporary allocations.
1013  *
1014  * @since New in 1.4.
1015  */
1016 svn_error_t *
1018  svn_stream_t *stream1,
1019  svn_stream_t *stream2,
1020  apr_pool_t *pool);
1021 
1022 
1023 /** Read the contents of @a stream into memory, returning the data in
1024  * @a result. The stream will be closed when it has been successfully and
1025  * completely read.
1026  *
1027  * The returned memory is allocated in @a result_pool, and any temporary
1028  * allocations are performed in @a scratch_pool.
1029  *
1030  * @note due to memory pseudo-reallocation behavior (due to pools), this
1031  * can be a memory-intensive operation for large files.
1032  *
1033  * @since New in 1.6
1034  */
1035 svn_error_t *
1037  svn_stream_t *stream,
1038  apr_pool_t *result_pool,
1039  apr_pool_t *scratch_pool);
1040 
1041 
1042 /** @} */
1043 
1044 /** Set @a *result to a string containing the contents of @a
1045  * filename, which is either "-" (indicating that stdin should be
1046  * read) or the utf8-encoded path of a real file.
1047  *
1048  * @warning Callers should be aware of possible unexpected results
1049  * when using this function to read from stdin where additional
1050  * stdin-reading processes abound. For example, if a program tries
1051  * both to invoke an external editor and to read from stdin, stdin
1052  * could be trashed and the editor might act funky or die outright.
1053  *
1054  * @note due to memory pseudo-reallocation behavior (due to pools), this
1055  * can be a memory-intensive operation for large files.
1056  *
1057  * @since New in 1.5.
1058  */
1059 svn_error_t *
1061  const char *filename,
1062  apr_pool_t *pool);
1063 
1064 /** Similar to svn_stringbuf_from_file2(), except that if @a filename
1065  * is "-", return the error @c SVN_ERR_UNSUPPORTED_FEATURE and don't
1066  * touch @a *result.
1067  *
1068  * @deprecated Provided for backwards compatibility with the 1.4 API.
1069  */
1071 svn_error_t *
1073  const char *filename,
1074  apr_pool_t *pool);
1075 
1076 /** Sets @a *result to a string containing the contents of the already opened
1077  * @a file. Reads from the current position in file to the end. Does not
1078  * close the file or reset the cursor position.
1079  *
1080  * @note due to memory pseudo-reallocation behavior (due to pools), this
1081  * can be a memory-intensive operation for large files.
1082  */
1083 svn_error_t *
1085  apr_file_t *file,
1086  apr_pool_t *pool);
1087 
1088 /** Remove file @a path, a utf8-encoded path. This wraps apr_file_remove(),
1089  * converting any error to a Subversion error.
1090  */
1091 svn_error_t *
1092 svn_io_remove_file(const char *path,
1093  apr_pool_t *pool);
1094 
1095 /** Recursively remove directory @a path. @a path is utf8-encoded.
1096  * If @a ignore_enoent is @c TRUE, don't fail if the target directory
1097  * doesn't exist. Use @a pool for temporary allocations.
1098  *
1099  * Because recursive delete of a directory tree can be a lengthy operation,
1100  * provide @a cancel_func and @a cancel_baton for interruptability.
1101  *
1102  * @since New in 1.5.
1103  */
1104 svn_error_t *
1105 svn_io_remove_dir2(const char *path,
1106  svn_boolean_t ignore_enoent,
1107  svn_cancel_func_t cancel_func,
1108  void *cancel_baton,
1109  apr_pool_t *pool);
1110 
1111 /** Similar to svn_io_remove_dir2(), but with @a ignore_enoent set to
1112  * @c FALSE and @a cancel_func and @a cancel_baton set to @c NULL.
1113  *
1114  * @deprecated Provided for backward compatibility with the 1.4 API
1115  */
1117 svn_error_t *
1118 svn_io_remove_dir(const char *path,
1119  apr_pool_t *pool);
1120 
1121 /** Read all of the disk entries in directory @a path, a utf8-encoded
1122  * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
1123  * undefined non-NULL values, allocated in @a pool.
1124  *
1125  * @note The `.' and `..' directories normally returned by
1126  * apr_dir_read() are NOT returned in the hash.
1127  *
1128  * @since New in 1.4.
1129  */
1130 svn_error_t *
1131 svn_io_get_dir_filenames(apr_hash_t **dirents,
1132  const char *path,
1133  apr_pool_t *pool);
1134 
1135 /** Read all of the disk entries in directory @a path, a utf8-encoded
1136  * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
1137  * @c svn_io_dirent_t structures, allocated in @a pool.
1138  *
1139  * @note The `.' and `..' directories normally returned by
1140  * apr_dir_read() are NOT returned in the hash.
1141  *
1142  * @note The kind field in the @a dirents is set according to the mapping
1143  * as documented for svn_io_check_path()
1144  *
1145  * @since New in 1.3.
1146  */
1147 svn_error_t *
1148 svn_io_get_dirents2(apr_hash_t **dirents,
1149  const char *path,
1150  apr_pool_t *pool);
1151 
1152 /** Similar to svn_io_get_dirents2(), but @a *dirents is a hash table
1153  * with @c svn_node_kind_t values.
1154  *
1155  * @deprecated Provided for backwards compatibility with the 1.2 API.
1156  */
1158 svn_error_t *
1159 svn_io_get_dirents(apr_hash_t **dirents,
1160  const char *path,
1161  apr_pool_t *pool);
1162 
1163 
1164 /** Callback function type for svn_io_dir_walk() */
1165 typedef svn_error_t * (*svn_io_walk_func_t)(void *baton,
1166  const char *path,
1167  const apr_finfo_t *finfo,
1168  apr_pool_t *pool);
1169 
1170 /** This function will recursively walk over the files and directories
1171  * rooted at @a dirname, a utf8-encoded path. For each file or directory,
1172  * @a walk_func is invoked, passing in the @a walk_baton, the utf8-encoded
1173  * full path to the entry, an @c apr_finfo_t structure, and a temporary
1174  * pool for allocations. For any directory, @a walk_func will be invoked
1175  * on the directory itself before being invoked on any subdirectories or
1176  * files within the directory.
1177  *
1178  * The set of information passed to @a walk_func is specified by @a wanted,
1179  * and the items specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME.
1180  *
1181  * All allocations will be performed in @a pool.
1182  */
1183 svn_error_t *
1184 svn_io_dir_walk(const char *dirname,
1185  apr_int32_t wanted,
1186  svn_io_walk_func_t walk_func,
1187  void *walk_baton,
1188  apr_pool_t *pool);
1189 
1190 /**
1191  * Start @a cmd with @a args, using utf8-encoded @a path as working
1192  * directory. Connect @a cmd's stdin, stdout, and stderr to @a infile,
1193  * @a outfile, and @a errfile, except where they are NULL. Return the
1194  * process handle for the invoked program in @a *cmd_proc.
1195  *
1196  * @a args is a list of utf8-encoded <tt>const char *</tt> arguments,
1197  * terminated by @c NULL. @a args[0] is the name of the program, though it
1198  * need not be the same as @a cmd.
1199  *
1200  * If @a inherit is TRUE, the invoked program inherits its environment from
1201  * the caller and @a cmd, if not absolute, is searched for in PATH.
1202  * Otherwise, the invoked program runs with an empty environment and @a cmd
1203  * must be an absolute path.
1204  *
1205  * @note On some platforms, failure to execute @a cmd in the child process
1206  * will result in error output being written to @a errfile, if non-NULL, and
1207  * a non-zero exit status being returned to the parent process.
1208  *
1209  * @since New in 1.3.
1210  */
1211 svn_error_t *
1212 svn_io_start_cmd(apr_proc_t *cmd_proc,
1213  const char *path,
1214  const char *cmd,
1215  const char *const *args,
1216  svn_boolean_t inherit,
1217  apr_file_t *infile,
1218  apr_file_t *outfile,
1219  apr_file_t *errfile,
1220  apr_pool_t *pool);
1221 
1222 /**
1223  * Wait for the process @a *cmd_proc to complete and optionally retrieve
1224  * its exit code. @a cmd is used only in error messages.
1225  *
1226  * If @a exitcode is not NULL, and SVN_NO_ERROR is returned, @a *exitcode
1227  * will contain the exit code of the process. If @a exitcode is NULL and
1228  * the exit code is non-zero, then an @c SVN_ERR_EXTERNAL_PROGRAM error
1229  * will be returned.
1230  *
1231  * If @a exitwhy is not NULL, and SVN_NO_ERROR is returned, @a *exitwhy
1232  * will indicate why the process terminated. If @a exitwhy is NULL,
1233  * and the exit reason is not @c APR_PROC_CHECK_EXIT(), then an
1234  * @c SVN_ERR_EXTERNAL_PROGRAM error will be returned.
1235  *
1236  * @since New in 1.3.
1237  */
1238 svn_error_t *
1239 svn_io_wait_for_cmd(apr_proc_t *cmd_proc,
1240  const char *cmd,
1241  int *exitcode,
1242  apr_exit_why_e *exitwhy,
1243  apr_pool_t *pool);
1244 
1245 /** Run a command to completion, by first calling svn_io_start_cmd() and
1246  * then calling svn_io_wait_for_cmd(). The parameters correspond to
1247  * the same-named parameters of those two functions.
1248  */
1249 svn_error_t *
1250 svn_io_run_cmd(const char *path,
1251  const char *cmd,
1252  const char *const *args,
1253  int *exitcode,
1254  apr_exit_why_e *exitwhy,
1255  svn_boolean_t inherit,
1256  apr_file_t *infile,
1257  apr_file_t *outfile,
1258  apr_file_t *errfile,
1259  apr_pool_t *pool);
1260 
1261 /** Invoke the configured @c diff program, with @a user_args (an array
1262  * of utf8-encoded @a num_user_args arguments) if they are specified
1263  * (that is, if @a user_args is non-NULL), or "-u" if they are not.
1264  * If @a user_args is NULL, the value of @a num_user_args is ignored.
1265  *
1266  * Diff runs in utf8-encoded @a dir, and its exit status is stored in
1267  * @a exitcode, if it is not @c NULL.
1268  *
1269  * If @a label1 and/or @a label2 are not NULL they will be passed to the diff
1270  * process as the arguments of "-L" options. @a label1 and @a label2 are also
1271  * in utf8, and will be converted to native charset along with the other args.
1272  *
1273  * @a from is the first file passed to diff, and @a to is the second. The
1274  * stdout of diff will be sent to @a outfile, and the stderr to @a errfile.
1275  *
1276  * @a diff_cmd must be non-NULL.
1277  *
1278  * Do all allocation in @a pool.
1279  * @since New in 1.6.0.
1280  */
1281 svn_error_t *
1282 svn_io_run_diff2(const char *dir,
1283  const char *const *user_args,
1284  int num_user_args,
1285  const char *label1,
1286  const char *label2,
1287  const char *from,
1288  const char *to,
1289  int *exitcode,
1290  apr_file_t *outfile,
1291  apr_file_t *errfile,
1292  const char *diff_cmd,
1293  apr_pool_t *pool);
1294 
1295 /** Similar to svn_io_run_diff2() but with @diff_cmd encoded in internal
1296  * encoding used by APR.
1297  *
1298  * @deprecated Provided for backwards compatibility with the 1.5 API. */
1300 svn_error_t *
1301 svn_io_run_diff(const char *dir,
1302  const char *const *user_args,
1303  int num_user_args,
1304  const char *label1,
1305  const char *label2,
1306  const char *from,
1307  const char *to,
1308  int *exitcode,
1309  apr_file_t *outfile,
1310  apr_file_t *errfile,
1311  const char *diff_cmd,
1312  apr_pool_t *pool);
1313 
1314 
1315 
1316 /** Invoke the configured @c diff3 program, in utf8-encoded @a dir
1317  * like this:
1318  *
1319  * diff3 -E -m @a mine @a older @a yours > @a merged
1320  *
1321  * (See the diff3 documentation for details.)
1322  *
1323  * If @a user_args is non-NULL, replace "-E" with the <tt>const char*</tt>
1324  * elements that @a user_args contains.
1325  *
1326  * @a mine, @a older and @a yours are utf8-encoded paths (relative to
1327  * @a dir or absolute) to three files that already exist.
1328  *
1329  * @a merged is an open file handle, and is left open after the merge
1330  * result is written to it. (@a merged should *not* be the same file
1331  * as @a mine, or nondeterministic things may happen!)
1332  *
1333  * @a mine_label, @a older_label, @a yours_label are utf8-encoded label
1334  * parameters for diff3's -L option. Any of them may be @c NULL, in
1335  * which case the corresponding @a mine, @a older, or @a yours parameter is
1336  * used instead.
1337  *
1338  * Set @a *exitcode to diff3's exit status. If @a *exitcode is anything
1339  * other than 0 or 1, then return @c SVN_ERR_EXTERNAL_PROGRAM. (Note the
1340  * following from the diff3 info pages: "An exit status of 0 means
1341  * `diff3' was successful, 1 means some conflicts were found, and 2
1342  * means trouble.")
1343  *
1344  * @a diff3_cmd must be non-NULL.
1345  *
1346  * Do all allocation in @a pool.
1347  *
1348  * @since New in 1.4.
1349  */
1350 svn_error_t *
1351 svn_io_run_diff3_3(int *exitcode,
1352  const char *dir,
1353  const char *mine,
1354  const char *older,
1355  const char *yours,
1356  const char *mine_label,
1357  const char *older_label,
1358  const char *yours_label,
1359  apr_file_t *merged,
1360  const char *diff3_cmd,
1361  const apr_array_header_t *user_args,
1362  apr_pool_t *pool);
1363 
1364 /** Similar to svn_io_run_diff3_3(), but with @a diff3_cmd encoded in
1365  * internal encoding used by APR.
1366  *
1367  * @deprecated Provided for backwards compatibility with the 1.5 API.
1368  * @since New in 1.4.
1369  */
1371 svn_error_t *
1372 svn_io_run_diff3_2(int *exitcode,
1373  const char *dir,
1374  const char *mine,
1375  const char *older,
1376  const char *yours,
1377  const char *mine_label,
1378  const char *older_label,
1379  const char *yours_label,
1380  apr_file_t *merged,
1381  const char *diff3_cmd,
1382  const apr_array_header_t *user_args,
1383  apr_pool_t *pool);
1384 
1385 /** Similar to svn_io_run_diff3_2(), but with @a user_args set to @c NULL.
1386  *
1387  * @deprecated Provided for backwards compatibility with the 1.3 API.
1388  */
1390 svn_error_t *
1391 svn_io_run_diff3(const char *dir,
1392  const char *mine,
1393  const char *older,
1394  const char *yours,
1395  const char *mine_label,
1396  const char *older_label,
1397  const char *yours_label,
1398  apr_file_t *merged,
1399  int *exitcode,
1400  const char *diff3_cmd,
1401  apr_pool_t *pool);
1402 
1403 
1404 /** Parse utf8-encoded @a mimetypes_file as a MIME types file (such as
1405  * is provided with Apache HTTP Server), and set @a *type_map to a
1406  * hash mapping <tt>const char *</tt> filename extensions to
1407  * <tt>const char *</tt> MIME types.
1408  *
1409  * @since New in 1.5.
1410  */
1411 svn_error_t *
1412 svn_io_parse_mimetypes_file(apr_hash_t **type_map,
1413  const char *mimetypes_file,
1414  apr_pool_t *pool);
1415 
1416 
1417 /** Examine utf8-encoded @a file to determine if it can be described by a
1418  * known (as in, known by this function) Multipurpose Internet Mail
1419  * Extension (MIME) type. If so, set @a *mimetype to a character string
1420  * describing the MIME type, else set it to @c NULL.
1421  *
1422  * If not @c NULL, @a mimetype_map is a hash mapping <tt>const char *</tt>
1423  * filename extensions to <tt>const char *</tt> MIME types, and is the
1424  * first source consulted regarding @a file's MIME type.
1425  *
1426  * Use @a pool for any necessary allocations.
1427  *
1428  * @since New in 1.5.
1429  */
1430 svn_error_t *
1431 svn_io_detect_mimetype2(const char **mimetype,
1432  const char *file,
1433  apr_hash_t *mimetype_map,
1434  apr_pool_t *pool);
1435 
1436 
1437 /** Like svn_io_detect_mimetype2, but with @a mimetypes_map set to
1438  * @c NULL.
1439  *
1440  * @deprecated Provided for backward compatibility with the 1.4 API
1441  */
1443 svn_error_t *
1444 svn_io_detect_mimetype(const char **mimetype,
1445  const char *file,
1446  apr_pool_t *pool);
1447 
1448 
1449 /** Wrapper for apr_file_open(). @a fname is utf8-encoded. */
1450 svn_error_t *
1451 svn_io_file_open(apr_file_t **new_file,
1452  const char *fname,
1453  apr_int32_t flag,
1454  apr_fileperms_t perm,
1455  apr_pool_t *pool);
1456 
1457 
1458 /** Wrapper for apr_file_close(). */
1459 svn_error_t *
1460 svn_io_file_close(apr_file_t *file,
1461  apr_pool_t *pool);
1462 
1463 
1464 /** Wrapper for apr_file_getc(). */
1465 svn_error_t *
1466 svn_io_file_getc(char *ch,
1467  apr_file_t *file,
1468  apr_pool_t *pool);
1469 
1470 
1471 /** Wrapper for apr_file_info_get(). */
1472 svn_error_t *
1473 svn_io_file_info_get(apr_finfo_t *finfo,
1474  apr_int32_t wanted,
1475  apr_file_t *file,
1476  apr_pool_t *pool);
1477 
1478 
1479 /** Wrapper for apr_file_read(). */
1480 svn_error_t *
1481 svn_io_file_read(apr_file_t *file,
1482  void *buf,
1483  apr_size_t *nbytes,
1484  apr_pool_t *pool);
1485 
1486 
1487 /** Wrapper for apr_file_read_full(). */
1488 svn_error_t *
1489 svn_io_file_read_full(apr_file_t *file,
1490  void *buf,
1491  apr_size_t nbytes,
1492  apr_size_t *bytes_read,
1493  apr_pool_t *pool);
1494 
1495 
1496 /** Wrapper for apr_file_seek(). */
1497 svn_error_t *
1498 svn_io_file_seek(apr_file_t *file,
1499  apr_seek_where_t where,
1500  apr_off_t *offset,
1501  apr_pool_t *pool);
1502 
1503 
1504 /** Wrapper for apr_file_write(). */
1505 svn_error_t *
1506 svn_io_file_write(apr_file_t *file,
1507  const void *buf,
1508  apr_size_t *nbytes,
1509  apr_pool_t *pool);
1510 
1511 
1512 /** Wrapper for apr_file_write_full(). */
1513 svn_error_t *
1514 svn_io_file_write_full(apr_file_t *file,
1515  const void *buf,
1516  apr_size_t nbytes,
1517  apr_size_t *bytes_written,
1518  apr_pool_t *pool);
1519 
1520 /**
1521  * Open a unique file in @a dirpath, and write @a nbytes from @a buf to
1522  * the file before closing it. Return the name of the newly created file
1523  * in @a *tmp_path, allocated in @a pool.
1524  *
1525  * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir().
1526  * (Note that when using the system-provided temp directory, it may not
1527  * be possibly to atomically rename the resulting file due to cross-device
1528  * issues.)
1529  *
1530  * The file will be deleted according to @a delete_when.
1531  *
1532  * @since New in 1.6.
1533  */
1534 svn_error_t *
1535 svn_io_write_unique(const char **tmp_path,
1536  const char *dirpath,
1537  const void *buf,
1538  apr_size_t nbytes,
1539  svn_io_file_del_t delete_when,
1540  apr_pool_t *pool);
1541 
1542 /** Wrapper for apr_file_trunc().
1543  * @since New in 1.6. */
1544 svn_error_t *
1545 svn_io_file_trunc(apr_file_t *file,
1546  apr_off_t offset,
1547  apr_pool_t *pool);
1548 
1549 
1550 /** Wrapper for apr_stat(). @a fname is utf8-encoded. */
1551 svn_error_t *
1552 svn_io_stat(apr_finfo_t *finfo,
1553  const char *fname,
1554  apr_int32_t wanted,
1555  apr_pool_t *pool);
1556 
1557 
1558 /** Wrapper for apr_file_rename(). @a from_path and @a to_path are
1559  * utf8-encoded.
1560  */
1561 svn_error_t *
1562 svn_io_file_rename(const char *from_path,
1563  const char *to_path,
1564  apr_pool_t *pool);
1565 
1566 
1567 /** Move the file from @a from_path to @a to_path, even across device
1568  * boundaries. Overwrite @a to_path if it exists.
1569  *
1570  * @note This function is different from svn_io_file_rename in that the
1571  * latter fails in the 'across device boundaries' case.
1572  *
1573  * @since New in 1.3.
1574  */
1575 svn_error_t *
1576 svn_io_file_move(const char *from_path,
1577  const char *to_path,
1578  apr_pool_t *pool);
1579 
1580 
1581 /** Wrapper for apr_dir_make(). @a path is utf8-encoded. */
1582 svn_error_t *
1583 svn_io_dir_make(const char *path,
1584  apr_fileperms_t perm,
1585  apr_pool_t *pool);
1586 
1587 /** Same as svn_io_dir_make(), but sets the hidden attribute on the
1588  directory on systems that support it. */
1589 svn_error_t *
1590 svn_io_dir_make_hidden(const char *path,
1591  apr_fileperms_t perm,
1592  apr_pool_t *pool);
1593 
1594 /**
1595  * Same as svn_io_dir_make(), but attempts to set the sgid on the
1596  * directory on systems that support it. Does not return an error if
1597  * the attempt to set the sgid bit fails. On Unix filesystems,
1598  * setting the sgid bit on a directory ensures that files and
1599  * subdirectories created within inherit group ownership from the
1600  * parent instead of from the primary gid.
1601  *
1602  * @since New in 1.1.
1603  */
1604 svn_error_t *
1605 svn_io_dir_make_sgid(const char *path,
1606  apr_fileperms_t perm,
1607  apr_pool_t *pool);
1608 
1609 /** Wrapper for apr_dir_open(). @a dirname is utf8-encoded. */
1610 svn_error_t *
1611 svn_io_dir_open(apr_dir_t **new_dir,
1612  const char *dirname,
1613  apr_pool_t *pool);
1614 
1615 
1616 /** Wrapper for apr_dir_remove(). @a dirname is utf8-encoded.
1617  * @note This function has this name to avoid confusion with
1618  * svn_io_remove_dir2(), which is recursive.
1619  */
1620 svn_error_t *
1621 svn_io_dir_remove_nonrecursive(const char *dirname,
1622  apr_pool_t *pool);
1623 
1624 
1625 /** Wrapper for apr_dir_read(). Ensures that @a finfo->name is
1626  * utf8-encoded, which means allocating @a finfo->name in @a pool,
1627  * which may or may not be the same as @a finfo's pool. Use @a pool
1628  * for error allocation as well.
1629  */
1630 svn_error_t *
1631 svn_io_dir_read(apr_finfo_t *finfo,
1632  apr_int32_t wanted,
1633  apr_dir_t *thedir,
1634  apr_pool_t *pool);
1635 
1636 
1637 
1638 /** Version/format files.
1639  *
1640  * @defgroup svn_io_format_files Version/format files
1641  * @{
1642  */
1643 
1644 /** Set @a *version to the integer that starts the file at @a path. If the
1645  * file does not begin with a series of digits followed by a newline,
1646  * return the error @c SVN_ERR_BAD_VERSION_FILE_FORMAT. Use @a pool for
1647  * all allocations.
1648  */
1649 svn_error_t *
1650 svn_io_read_version_file(int *version,
1651  const char *path,
1652  apr_pool_t *pool);
1653 
1654 /** Create (or overwrite) the file at @a path with new contents,
1655  * formatted as a non-negative integer @a version followed by a single
1656  * newline. On successful completion the file will be read-only. Use
1657  * @a pool for all allocations.
1658  */
1659 svn_error_t *
1660 svn_io_write_version_file(const char *path,
1661  int version,
1662  apr_pool_t *pool);
1663 
1664 /** @} */
1665 
1666 #ifdef __cplusplus
1667 }
1668 #endif /* __cplusplus */
1669 
1670 #endif /* SVN_IO_H */