1/** 2 * @copyright 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 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 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 19 * under the License. 20 * ==================================================================== 21 * @endcopyright 22 * 23 * @file svn_io.h 24 * @brief General file I/O for Subversion 25 */ 26 27/* ==================================================================== */ 28 29 30#ifndef SVN_IO_H 31#define SVN_IO_H 32 33#include <apr.h> 34#include <apr_pools.h> 35#include <apr_time.h> 36#include <apr_hash.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 */ 41 42#include "svn_types.h" 43#include "svn_string.h" 44#include "svn_checksum.h" 45 46#ifdef __cplusplus 47extern "C" { 48#endif /* __cplusplus */ 49 50 51 52/** Used as an argument when creating temporary files to indicate 53 * when a file should be removed. 54 * 55 * @since New in 1.4. 56 * 57 * Not specifying any of these means no removal at all. */ 58typedef enum svn_io_file_del_t 59{ 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 66} svn_io_file_del_t; 67 68/** A set of directory entry data elements as returned by svn_io_get_dirents 69 * 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. 72 * 73 * Use svn_io_dirent2_create() to create new svn_dirent2_t instances or 74 * svn_io_dirent2_dup() to duplicate an existing instance. 75 * 76 * @since New in 1.7. 77 */ 78typedef struct svn_io_dirent2_t { 79 /* New fields must be added at the end to preserve binary compatibility */ 80 81 /** The kind of this entry. */ 82 svn_node_kind_t kind; 83 84 /** If @c kind is #svn_node_file, whether this entry is a special file; 85 * else FALSE. 86 * 87 * @see svn_io_check_special_path(). 88 */ 89 svn_boolean_t special; 90 91 /** The filesize of this entry or undefined for a directory */ 92 svn_filesize_t filesize; 93 94 /** The time the file was last modified */ 95 apr_time_t mtime; 96 97 /* Don't forget to update svn_io_dirent2_dup() when adding new fields */ 98} svn_io_dirent2_t; 99 100 101/** Creates a new #svn_io_dirent2_t structure 102 * 103 * @since New in 1.7. 104 */ 105svn_io_dirent2_t * 106svn_io_dirent2_create(apr_pool_t *result_pool); 107 108/** Duplicates a @c svn_io_dirent2_t structure into @a result_pool. 109 * 110 * @since New in 1.7. 111 */ 112svn_io_dirent2_t * 113svn_io_dirent2_dup(const svn_io_dirent2_t *item, 114 apr_pool_t *result_pool); 115 116/** Represents the kind and special status of a directory entry. 117 * 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. 120 * 121 * @since New in 1.3. 122 */ 123typedef 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; 127 * else FALSE. 128 * 129 * @see svn_io_check_special_path(). 130 */ 131 svn_boolean_t special; 132} svn_io_dirent_t; 133 134/** Determine the @a kind of @a path. @a path should be UTF-8 encoded. 135 * 136 * If @a path is a file, set @a *kind to #svn_node_file. 137 * 138 * If @a path is a directory, set @a *kind to #svn_node_dir. 139 * 140 * If @a path does not exist, set @a *kind to #svn_node_none. 141 * 142 * If @a path exists but is none of the above, set @a *kind to 143 * #svn_node_unknown. 144 * 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. 148 * 149 * Use @a pool for temporary allocations. 150 * 151 * @see svn_node_kind_t 152 */ 153svn_error_t * 154svn_io_check_path(const char *path, 155 svn_node_kind_t *kind, 156 apr_pool_t *pool); 157 158/** 159 * Like svn_io_check_path(), but also set *is_special to @c TRUE if 160 * the path is not a normal file. 161 * 162 * @since New in 1.1. 163 */ 164svn_error_t * 165svn_io_check_special_path(const char *path, 166 svn_node_kind_t *kind, 167 svn_boolean_t *is_special, 168 apr_pool_t *pool); 169 170/** Like svn_io_check_path(), but resolve symlinks. This returns the 171 same varieties of @a kind as svn_io_check_path(). */ 172svn_error_t * 173svn_io_check_resolved_path(const char *path, 174 svn_node_kind_t *kind, 175 apr_pool_t *pool); 176 177 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 183 * open. 184 * 185 * If @a delete_when is #svn_io_file_del_on_close, then the @c APR_DELONCLOSE 186 * flag will be used when opening the file. The @c APR_BUFFERED flag will 187 * always be used. 188 * 189 * The first attempt will just append @a suffix. If the result is not 190 * a unique name, then subsequent attempts will append a dot, 191 * followed by an iteration number ("2", then "3", and so on), 192 * followed by the suffix. For example, successive calls to 193 * 194 * svn_io_open_uniquely_named(&f, &u, "tests/t1/A/D/G", "pi", ".tmp", ...) 195 * 196 * will open 197 * 198 * tests/t1/A/D/G/pi.tmp 199 * tests/t1/A/D/G/pi.2.tmp 200 * tests/t1/A/D/G/pi.3.tmp 201 * tests/t1/A/D/G/pi.4.tmp 202 * tests/t1/A/D/G/pi.5.tmp 203 * ... 204 * 205 * Assuming @a suffix is non-empty, @a *unique_name will never be exactly 206 * the same as @a filename, even if @a filename does not exist. 207 * 208 * If @a dirpath is NULL, then the directory returned by svn_io_temp_dir() 209 * will be used. 210 * 211 * If @a filename is NULL, then "tempfile" will be used. 212 * 213 * If @a suffix is NULL, then ".tmp" will be used. 214 * 215 * Allocates @a *file and @a *unique_name in @a result_pool. All 216 * intermediate allocations will be performed in @a scratch_pool. 217 * 218 * If no unique name can be found, #SVN_ERR_IO_UNIQUE_NAMES_EXHAUSTED is 219 * the error returned. 220 * 221 * Claim of Historical Inevitability: this function was written 222 * because 223 * 224 * - tmpnam() is not thread-safe. 225 * - tempname() tries standard system tmp areas first. 226 * 227 * @since New in 1.6 228 */ 229svn_error_t * 230svn_io_open_uniquely_named(apr_file_t **file, 231 const char **unique_name, 232 const char *dirpath, 233 const char *filename, 234 const char *suffix, 235 svn_io_file_del_t delete_when, 236 apr_pool_t *result_pool, 237 apr_pool_t *scratch_pool); 238 239 240/** Create a writable file, with an arbitrary and unique name, in the 241 * directory @a dirpath. Set @a *temp_path to its full path, and set 242 * @a *file to the file handle, both allocated from @a result_pool. Either 243 * @a file or @a temp_path may be @c NULL. If @a file is @c NULL, the file 244 * will be created but not open. 245 * 246 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir(). 247 * (Note that when using the system-provided temp directory, it may not 248 * be possible to atomically rename the resulting file due to cross-device 249 * issues.) 250 * 251 * The file will be deleted according to @a delete_when. If @a delete_when 252 * is @c svn_io_file_del_on_close and @a file is @c NULL, the file will be 253 * deleted before this function returns. 254 * 255 * When passing @c svn_io_file_del_none please don't forget to eventually 256 * remove the temporary file to avoid filling up the system temp directory. 257 * It is often appropriate to bind the lifetime of the temporary file to 258 * the lifetime of a pool by using @c svn_io_file_del_on_pool_cleanup. 259 * 260 * Temporary allocations will be performed in @a scratch_pool. 261 * 262 * @since New in 1.6 263 * @see svn_stream_open_unique() 264 */ 265svn_error_t * 266svn_io_open_unique_file3(apr_file_t **file, 267 const char **temp_path, 268 const char *dirpath, 269 svn_io_file_del_t delete_when, 270 apr_pool_t *result_pool, 271 apr_pool_t *scratch_pool); 272 273 274/** Like svn_io_open_uniquely_named(), but takes a joined dirpath and 275 * filename, and a single pool. 276 * 277 * @since New in 1.4 278 * 279 * @deprecated Provided for backward compatibility with the 1.5 API 280 */ 281SVN_DEPRECATED 282svn_error_t * 283svn_io_open_unique_file2(apr_file_t **f, 284 const char **unique_name_p, 285 const char *path, 286 const char *suffix, 287 svn_io_file_del_t delete_when, 288 apr_pool_t *pool); 289 290/** Like svn_io_open_unique_file2, but can't delete on pool cleanup. 291 * 292 * @deprecated Provided for backward compatibility with the 1.3 API 293 * 294 * @note In 1.4 the API was extended to require either @a f or 295 * @a unique_name_p (the other can be NULL). Before that, both were 296 * required. 297 */ 298SVN_DEPRECATED 299svn_error_t * 300svn_io_open_unique_file(apr_file_t **f, 301 const char **unique_name_p, 302 const char *path, 303 const char *suffix, 304 svn_boolean_t delete_on_close, 305 apr_pool_t *pool); 306 307 308/** 309 * Like svn_io_open_unique_file(), except that instead of creating a 310 * file, a symlink is generated that references the path @a dest. 311 * 312 * @since New in 1.1. 313 */ 314svn_error_t * 315svn_io_create_unique_link(const char **unique_name_p, 316 const char *path, 317 const char *dest, 318 const char *suffix, 319 apr_pool_t *pool); 320 321 322/** 323 * Set @a *dest to the path that the symlink at @a path references. 324 * Allocate the string from @a pool. 325 * 326 * @since New in 1.1. 327 */ 328svn_error_t * 329svn_io_read_link(svn_string_t **dest, 330 const char *path, 331 apr_pool_t *pool); 332 333 334/** Set @a *dir to a directory path (allocated in @a pool) deemed 335 * usable for the creation of temporary files and subdirectories. 336 */ 337svn_error_t * 338svn_io_temp_dir(const char **dir, 339 apr_pool_t *pool); 340 341 342/** Copy @a src to @a dst atomically, in a "byte-for-byte" manner. 343 * Overwrite @a dst if it exists, else create it. Both @a src and @a dst 344 * are utf8-encoded filenames. If @a copy_perms is TRUE, set @a dst's 345 * permissions to match those of @a src. 346 */ 347svn_error_t * 348svn_io_copy_file(const char *src, 349 const char *dst, 350 svn_boolean_t copy_perms, 351 apr_pool_t *pool); 352 353 354/** Copy permission flags from @a src onto the file at @a dst. Both 355 * filenames are utf8-encoded filenames. 356 * 357 * @since New in 1.6. 358 */ 359svn_error_t * 360svn_io_copy_perms(const char *src, 361 const char *dst, 362 apr_pool_t *pool); 363 364 365/** 366 * Copy symbolic link @a src to @a dst atomically. Overwrite @a dst 367 * if it exists, else create it. Both @a src and @a dst are 368 * utf8-encoded filenames. After copying, the @a dst link will point 369 * to the same thing @a src does. 370 * 371 * @since New in 1.1. 372 */ 373svn_error_t * 374svn_io_copy_link(const char *src, 375 const char *dst, 376 apr_pool_t *pool); 377 378 379/** Recursively copy directory @a src into @a dst_parent, as a new entry named 380 * @a dst_basename. If @a dst_basename already exists in @a dst_parent, 381 * return error. @a copy_perms will be passed through to svn_io_copy_file() 382 * when any files are copied. @a src, @a dst_parent, and @a dst_basename are 383 * all utf8-encoded. 384 * 385 * If @a cancel_func is non-NULL, invoke it with @a cancel_baton at 386 * various points during the operation. If it returns any error 387 * (typically #SVN_ERR_CANCELLED), return that error immediately. 388 */ 389svn_error_t * 390svn_io_copy_dir_recursively(const char *src, 391 const char *dst_parent, 392 const char *dst_basename, 393 svn_boolean_t copy_perms, 394 svn_cancel_func_t cancel_func, 395 void *cancel_baton, 396 apr_pool_t *pool); 397 398 399/** Create directory @a path on the file system, creating intermediate 400 * directories as required, like <tt>mkdir -p</tt>. Report no error if @a 401 * path already exists. @a path is utf8-encoded. 402 * 403 * This is essentially a wrapper for apr_dir_make_recursive(), passing 404 * @c APR_OS_DEFAULT as the permissions. 405 */ 406svn_error_t * 407svn_io_make_dir_recursively(const char *path, 408 apr_pool_t *pool); 409 410 411/** Set @a *is_empty_p to @c TRUE if directory @a path is empty, else to 412 * @c FALSE if it is not empty. @a path must be a directory, and is 413 * utf8-encoded. Use @a pool for temporary allocation. 414 */ 415svn_error_t * 416svn_io_dir_empty(svn_boolean_t *is_empty_p, 417 const char *path, 418 apr_pool_t *pool); 419 420 421/** Append @a src to @a dst. @a dst will be appended to if it exists, else it 422 * will be created. Both @a src and @a dst are utf8-encoded. 423 */ 424svn_error_t * 425svn_io_append_file(const char *src, 426 const char *dst, 427 apr_pool_t *pool); 428 429 430/** Make a file as read-only as the operating system allows. 431 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is 432 * @c TRUE, don't fail if the target file doesn't exist. 433 * 434 * If @a path is a symlink, do nothing. 435 * 436 * @note If @a path is a directory, act on it as though it were a 437 * file, as described above, but note that you probably don't want to 438 * call this function on directories. We have left it effective on 439 * directories for compatibility reasons, but as its name implies, it 440 * should be used only for files. 441 */ 442svn_error_t * 443svn_io_set_file_read_only(const char *path, 444 svn_boolean_t ignore_enoent, 445 apr_pool_t *pool); 446 447 448/** Make a file as writable as the operating system allows. 449 * @a path is the utf8-encoded path to the file. If @a ignore_enoent is 450 * @c TRUE, don't fail if the target file doesn't exist. 451 * @warning On Unix this function will do the equivalent of chmod a+w path. 452 * If this is not what you want you should not use this function, but rather 453 * use apr_file_perms_set(). 454 * 455 * If @a path is a symlink, do nothing. 456 * 457 * @note If @a path is a directory, act on it as though it were a 458 * file, as described above, but note that you probably don't want to 459 * call this function on directories. We have left it effective on 460 * directories for compatibility reasons, but as its name implies, it 461 * should be used only for files. 462 */ 463svn_error_t * 464svn_io_set_file_read_write(const char *path, 465 svn_boolean_t ignore_enoent, 466 apr_pool_t *pool); 467 468 469/** Similar to svn_io_set_file_read_* functions. 470 * Change the read-write permissions of a file. 471 * @since New in 1.1. 472 * 473 * When making @a path read-write on operating systems with unix style 474 * permissions, set the permissions on @a path to the permissions that 475 * are set when a new file is created (effectively honoring the user's 476 * umask). 477 * 478 * When making the file read-only on operating systems with unix style 479 * permissions, remove all write permissions. 480 * 481 * On other operating systems, toggle the file's "writability" as much as 482 * the operating system allows. 483 * 484 * @a path is the utf8-encoded path to the file. If @a enable_write 485 * is @c TRUE, then make the file read-write. If @c FALSE, make it 486 * read-only. If @a ignore_enoent is @c TRUE, don't fail if the target 487 * file doesn't exist. 488 * 489 * @deprecated Provided for backward compatibility with the 1.3 API. 490 */ 491SVN_DEPRECATED 492svn_error_t * 493svn_io_set_file_read_write_carefully(const char *path, 494 svn_boolean_t enable_write, 495 svn_boolean_t ignore_enoent, 496 apr_pool_t *pool); 497 498/** Set @a path's "executability" (but do nothing if it is a symlink). 499 * 500 * @a path is the utf8-encoded path to the file. If @a executable 501 * is @c TRUE, then make the file executable. If @c FALSE, make it 502 * non-executable. If @a ignore_enoent is @c TRUE, don't fail if the target 503 * file doesn't exist. 504 * 505 * When making the file executable on operating systems with unix style 506 * permissions, never add an execute permission where there is not 507 * already a read permission: that is, only make the file executable 508 * for the user, group or world if the corresponding read permission 509 * is already set for user, group or world. 510 * 511 * When making the file non-executable on operating systems with unix style 512 * permissions, remove all execute permissions. 513 * 514 * On other operating systems, toggle the file's "executability" as much as 515 * the operating system allows. 516 * 517 * @note If @a path is a directory, act on it as though it were a 518 * file, as described above, but note that you probably don't want to 519 * call this function on directories. We have left it effective on 520 * directories for compatibility reasons, but as its name implies, it 521 * should be used only for files. 522 */ 523svn_error_t * 524svn_io_set_file_executable(const char *path, 525 svn_boolean_t executable, 526 svn_boolean_t ignore_enoent, 527 apr_pool_t *pool); 528 529/** Determine whether a file is executable by the current user. 530 * Set @a *executable to @c TRUE if the file @a path is executable by the 531 * current user, otherwise set it to @c FALSE. 532 * 533 * On Windows and on platforms without userids, always returns @c FALSE. 534 */ 535svn_error_t * 536svn_io_is_file_executable(svn_boolean_t *executable, 537 const char *path, 538 apr_pool_t *pool); 539 540 541/** Read a line from @a file into @a buf, but not exceeding @a *limit bytes. 542 * Does not include newline, instead '\\0' is put there. 543 * Length (as in strlen) is returned in @a *limit. 544 * @a buf should be pre-allocated. 545 * @a file should be already opened. 546 * 547 * When the file is out of lines, @c APR_EOF will be returned. 548 */ 549svn_error_t * 550svn_io_read_length_line(apr_file_t *file, 551 char *buf, 552 apr_size_t *limit, 553 apr_pool_t *pool); 554 555 556/** Set @a *apr_time to the time of last modification of the contents of the 557 * file @a path. @a path is utf8-encoded. 558 * 559 * @note This is the APR mtime which corresponds to the traditional mtime 560 * on Unix, and the last write time on Windows. 561 */ 562svn_error_t * 563svn_io_file_affected_time(apr_time_t *apr_time, 564 const char *path, 565 apr_pool_t *pool); 566 567/** Set the timestamp of file @a path to @a apr_time. @a path is 568 * utf8-encoded. 569 * 570 * @note This is the APR mtime which corresponds to the traditional mtime 571 * on Unix, and the last write time on Windows. 572 */ 573svn_error_t * 574svn_io_set_file_affected_time(apr_time_t apr_time, 575 const char *path, 576 apr_pool_t *pool); 577 578/** Sleep to ensure that any files modified after we exit have a different 579 * timestamp than the one we recorded. If @a path is not NULL, check if we 580 * can determine how long we should wait for a new timestamp on the filesystem 581 * containing @a path, an existing file or directory. If @a path is NULL or we 582 * can't determine the timestamp resolution, sleep until the next second. 583 * 584 * Use @a pool for any necessary allocations. @a pool can be null if @a path 585 * is NULL. 586 * 587 * Errors while retrieving the timestamp resolution will result in sleeping 588 * to the next second, to keep the working copy stable in error conditions. 589 * 590 * @since New in 1.6. 591 */ 592void 593svn_io_sleep_for_timestamps(const char *path, apr_pool_t *pool); 594 595/** Set @a *different_p to TRUE if @a file1 and @a file2 have different 596 * sizes, else set to FALSE. Both @a file1 and @a file2 are utf8-encoded. 597 * 598 * Setting @a *different_p to zero does not mean the files definitely 599 * have the same size, it merely means that the sizes are not 600 * definitely different. That is, if the size of one or both files 601 * cannot be determined, then the sizes are not known to be different, 602 * so @a *different_p is set to FALSE. 603 */ 604svn_error_t * 605svn_io_filesizes_different_p(svn_boolean_t *different_p, 606 const char *file1, 607 const char *file2, 608 apr_pool_t *pool); 609 610/** Set @a *different_p12 to non-zero if @a file1 and @a file2 have different 611 * sizes, else set to zero. Do the similar for @a *different_p23 with 612 * @a file2 and @a file3, and @a *different_p13 for @a file1 and @a file3. 613 * The filenames @a file1, @a file2 and @a file3 are utf8-encoded. 614 * 615 * Setting @a *different_p12 to zero does not mean the files definitely 616 * have the same size, it merely means that the sizes are not 617 * definitely different. That is, if the size of one or both files 618 * cannot be determined (due to stat() returning an error), then the sizes 619 * are not known to be different, so @a *different_p12 is set to 0. 620 * 621 * @since New in 1.8. 622 */ 623svn_error_t * 624svn_io_filesizes_three_different_p(svn_boolean_t *different_p12, 625 svn_boolean_t *different_p23, 626 svn_boolean_t *different_p13, 627 const char *file1, 628 const char *file2, 629 const char *file3, 630 apr_pool_t *scratch_pool); 631 632/** Return in @a *checksum the checksum of type @a kind of @a file 633 * Use @a pool for temporary allocations and to allocate @a *checksum. 634 * 635 * @since New in 1.6. 636 */ 637svn_error_t * 638svn_io_file_checksum2(svn_checksum_t **checksum, 639 const char *file, 640 svn_checksum_kind_t kind, 641 apr_pool_t *pool); 642 643 644/** Put the md5 checksum of @a file into @a digest. 645 * @a digest points to @c APR_MD5_DIGESTSIZE bytes of storage. 646 * Use @a pool only for temporary allocations. 647 * 648 * @deprecated Provided for backward compatibility with the 1.5 API. 649 */ 650SVN_DEPRECATED 651svn_error_t * 652svn_io_file_checksum(unsigned char digest[], 653 const char *file, 654 apr_pool_t *pool); 655 656 657/** Set @a *same to TRUE if @a file1 and @a file2 have the same 658 * contents, else set it to FALSE. Use @a pool for temporary allocations. 659 */ 660svn_error_t * 661svn_io_files_contents_same_p(svn_boolean_t *same, 662 const char *file1, 663 const char *file2, 664 apr_pool_t *pool); 665 666/** Set @a *same12 to TRUE if @a file1 and @a file2 have the same 667 * contents, else set it to FALSE. Do the similar for @a *same23 668 * with @a file2 and @a file3, and @a *same13 for @a file1 and @a 669 * file3. The filenames @a file1, @a file2 and @a file3 are 670 * utf8-encoded. Use @a scratch_pool for temporary allocations. 671 * 672 * @since New in 1.8. 673 */ 674svn_error_t * 675svn_io_files_contents_three_same_p(svn_boolean_t *same12, 676 svn_boolean_t *same23, 677 svn_boolean_t *same13, 678 const char *file1, 679 const char *file2, 680 const char *file3, 681 apr_pool_t *scratch_pool); 682 683/** Create file at utf8-encoded @a file with contents @a contents. 684 * @a file must not already exist. 685 * Use @a pool for memory allocations. 686 */ 687svn_error_t * 688svn_io_file_create(const char *file, 689 const char *contents, 690 apr_pool_t *pool); 691 692/** 693 * Lock file at @a lock_file. If @a exclusive is TRUE, 694 * obtain exclusive lock, otherwise obtain shared lock. 695 * Lock will be automatically released when @a pool is cleared or destroyed. 696 * Use @a pool for memory allocations. 697 * 698 * @deprecated Provided for backward compatibility with the 1.0 API. 699 */ 700SVN_DEPRECATED 701svn_error_t * 702svn_io_file_lock(const char *lock_file, 703 svn_boolean_t exclusive, 704 apr_pool_t *pool); 705 706/** 707 * Lock file at @a lock_file. If @a exclusive is TRUE, 708 * obtain exclusive lock, otherwise obtain shared lock. 709 * 710 * If @a nonblocking is TRUE, do not wait for the lock if it 711 * is not available: throw an error instead. 712 * 713 * Lock will be automatically released when @a pool is cleared or destroyed. 714 * Use @a pool for memory allocations. 715 * 716 * @since New in 1.1. 717 */ 718svn_error_t * 719svn_io_file_lock2(const char *lock_file, 720 svn_boolean_t exclusive, 721 svn_boolean_t nonblocking, 722 apr_pool_t *pool); 723 724/** 725 * Lock the file @a lockfile_handle. If @a exclusive is TRUE, 726 * obtain exclusive lock, otherwise obtain shared lock. 727 * 728 * If @a nonblocking is TRUE, do not wait for the lock if it 729 * is not available: throw an error instead. 730 * 731 * Lock will be automatically released when @a pool is cleared or destroyed. 732 * You may also explicitly call svn_io_unlock_open_file(). 733 * Use @a pool for memory allocations. @a pool must be the pool that 734 * @a lockfile_handle has been created in or one of its sub-pools. 735 * 736 * @since New in 1.8. 737 */ 738svn_error_t * 739svn_io_lock_open_file(apr_file_t *lockfile_handle, 740 svn_boolean_t exclusive, 741 svn_boolean_t nonblocking, 742 apr_pool_t *pool); 743 744/** 745 * Unlock the file @a lockfile_handle. 746 * 747 * Use @a pool for memory allocations. @a pool must be the pool that 748 * was passed to svn_io_lock_open_file(). 749 * 750 * @since New in 1.8. 751 */ 752svn_error_t * 753svn_io_unlock_open_file(apr_file_t *lockfile_handle, 754 apr_pool_t *pool); 755 756/** 757 * Flush any unwritten data from @a file to disk. Use @a pool for 758 * memory allocations. 759 * 760 * @since New in 1.1. 761 */ 762svn_error_t * 763svn_io_file_flush_to_disk(apr_file_t *file, 764 apr_pool_t *pool); 765 766/** Copy the file whose basename (or relative path) is @a file within 767 * directory @a src_path to the same basename (or relative path) within 768 * directory @a dest_path. Overwrite the destination file if it already 769 * exists. The destination directory (including any directory 770 * components in @a name) must already exist. Set the destination 771 * file's permissions to match those of the source. Use @a pool for 772 * memory allocations. 773 */ 774svn_error_t * 775svn_io_dir_file_copy(const char *src_path, 776 const char *dest_path, 777 const char *file, 778 apr_pool_t *pool); 779 780 781/** Generic byte-streams 782 * 783 * @defgroup svn_io_byte_streams Generic byte streams 784 * @{ 785 */ 786 787/** An abstract stream of bytes--either incoming or outgoing or both. 788 * 789 * The creator of a stream sets functions to handle read and write. 790 * Both of these handlers accept a baton whose value is determined at 791 * stream creation time; this baton can point to a structure 792 * containing data associated with the stream. If a caller attempts 793 * to invoke a handler which has not been set, it will generate a 794 * runtime assertion failure. The creator can also set a handler for 795 * close requests so that it can flush buffered data or whatever; 796 * if a close handler is not specified, a close request on the stream 797 * will simply be ignored. Note that svn_stream_close() does not 798 * deallocate the memory used to allocate the stream structure; free 799 * the pool you created the stream in to free that memory. 800 * 801 * The read and write handlers accept length arguments via pointer. 802 * On entry to the handler, the pointed-to value should be the amount 803 * of data which can be read or the amount of data to write. When the 804 * handler returns, the value is reset to the amount of data actually 805 * read or written. Handlers are obliged to complete a read or write 806 * to the maximum extent possible; thus, a short read with no 807 * associated error implies the end of the input stream, and a short 808 * write should never occur without an associated error. 809 * 810 * In Subversion 1.7 reset support was added as an optional feature of 811 * streams. If a stream implements resetting it allows reading the data 812 * again after a successful call to svn_stream_reset(). 813 */ 814typedef struct svn_stream_t svn_stream_t; 815 816 817 818/** Read handler function for a generic stream. @see svn_stream_t. */ 819typedef svn_error_t *(*svn_read_fn_t)(void *baton, 820 char *buffer, 821 apr_size_t *len); 822 823/** Skip data handler function for a generic stream. @see svn_stream_t 824 * and svn_stream_skip(). 825 * @since New in 1.7. 826 */ 827typedef svn_error_t *(*svn_stream_skip_fn_t)(void *baton, 828 apr_size_t len); 829 830/** Write handler function for a generic stream. @see svn_stream_t. */ 831typedef svn_error_t *(*svn_write_fn_t)(void *baton, 832 const char *data, 833 apr_size_t *len); 834 835/** Close handler function for a generic stream. @see svn_stream_t. */ 836typedef svn_error_t *(*svn_close_fn_t)(void *baton); 837 838/** An opaque type which represents a mark on a stream. There is no 839 * concrete definition of this type, it is a named type for stream 840 * implementation specific baton pointers. 841 * 842 * @see svn_stream_mark(). 843 * @since New in 1.7. 844 */ 845typedef struct svn_stream_mark_t svn_stream_mark_t; 846 847/** Mark handler function for a generic stream. @see svn_stream_t and 848 * svn_stream_mark(). 849 * 850 * @since New in 1.7. 851 */ 852typedef svn_error_t *(*svn_stream_mark_fn_t)(void *baton, 853 svn_stream_mark_t **mark, 854 apr_pool_t *pool); 855 856/** Seek handler function for a generic stream. @see svn_stream_t and 857 * svn_stream_seek(). 858 * 859 * @since New in 1.7. 860 */ 861typedef svn_error_t *(*svn_stream_seek_fn_t)(void *baton, 862 const svn_stream_mark_t *mark); 863 864/** Create a generic stream. @see svn_stream_t. */ 865svn_stream_t * 866svn_stream_create(void *baton, 867 apr_pool_t *pool); 868 869/** Set @a stream's baton to @a baton */ 870void 871svn_stream_set_baton(svn_stream_t *stream, 872 void *baton); 873 874/** Set @a stream's read function to @a read_fn */ 875void 876svn_stream_set_read(svn_stream_t *stream, 877 svn_read_fn_t read_fn); 878 879/** Set @a stream's skip function to @a skip_fn 880 * 881 * @since New in 1.7 882 */ 883void 884svn_stream_set_skip(svn_stream_t *stream, 885 svn_stream_skip_fn_t skip_fn); 886 887/** Set @a stream's write function to @a write_fn */ 888void 889svn_stream_set_write(svn_stream_t *stream, 890 svn_write_fn_t write_fn); 891 892/** Set @a stream's close function to @a close_fn */ 893void 894svn_stream_set_close(svn_stream_t *stream, 895 svn_close_fn_t close_fn); 896 897/** Set @a stream's mark function to @a mark_fn 898 * 899 * @since New in 1.7. 900 */ 901void 902svn_stream_set_mark(svn_stream_t *stream, 903 svn_stream_mark_fn_t mark_fn); 904 905/** Set @a stream's seek function to @a seek_fn 906 * 907 * @since New in 1.7. 908 */ 909void 910svn_stream_set_seek(svn_stream_t *stream, 911 svn_stream_seek_fn_t seek_fn); 912 913/** Create a stream that is empty for reading and infinite for writing. */ 914svn_stream_t * 915svn_stream_empty(apr_pool_t *pool); 916 917/** Return a stream allocated in @a pool which forwards all requests 918 * to @a stream. Destruction is explicitly excluded from forwarding. 919 * 920 * @see notes/destruction-of-stacked-resources 921 * 922 * @since New in 1.4. 923 */ 924svn_stream_t * 925svn_stream_disown(svn_stream_t *stream, 926 apr_pool_t *pool); 927 928 929/** Create a stream to read the file at @a path. It will be opened using 930 * the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the perms. 931 * If you'd like to use different values, then open the file yourself, and 932 * use the svn_stream_from_aprfile2() interface. 933 * 934 * The stream will be returned in @a stream, and allocated from @a result_pool. 935 * Temporary allocations will be performed in @a scratch_pool. 936 * 937 * @since New in 1.6 938 */ 939svn_error_t * 940svn_stream_open_readonly(svn_stream_t **stream, 941 const char *path, 942 apr_pool_t *result_pool, 943 apr_pool_t *scratch_pool); 944 945 946/** Create a stream to write a file at @a path. The file will be *created* 947 * using the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the 948 * perms. The file will be created "exclusively", so if it already exists, 949 * then an error will be thrown. If you'd like to use different values, or 950 * open an existing file, then open the file yourself, and use the 951 * svn_stream_from_aprfile2() interface. 952 * 953 * The stream will be returned in @a stream, and allocated from @a result_pool. 954 * Temporary allocations will be performed in @a scratch_pool. 955 * 956 * @since New in 1.6 957 */ 958svn_error_t * 959svn_stream_open_writable(svn_stream_t **stream, 960 const char *path, 961 apr_pool_t *result_pool, 962 apr_pool_t *scratch_pool); 963 964 965/** Create a writable stream to a file in the directory @a dirpath. 966 * The file will have an arbitrary and unique name, and the full path 967 * will be returned in @a temp_path. The stream will be returned in 968 * @a stream. Both will be allocated from @a result_pool. 969 * 970 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir(). 971 * (Note that when using the system-provided temp directory, it may not 972 * be possible to atomically rename the resulting file due to cross-device 973 * issues.) 974 * 975 * The file will be deleted according to @a delete_when. 976 * 977 * Temporary allocations will be performed in @a scratch_pool. 978 * 979 * @since New in 1.6 980 * @see svn_io_open_unique_file3() 981 */ 982svn_error_t * 983svn_stream_open_unique(svn_stream_t **stream, 984 const char **temp_path, 985 const char *dirpath, 986 svn_io_file_del_t delete_when, 987 apr_pool_t *result_pool, 988 apr_pool_t *scratch_pool); 989 990 991/** Create a stream from an APR file. For convenience, if @a file is 992 * @c NULL, an empty stream created by svn_stream_empty() is returned. 993 * 994 * This function should normally be called with @a disown set to FALSE, 995 * in which case closing the stream will also close the underlying file. 996 * 997 * If @a disown is TRUE, the stream will disown the underlying file, 998 * meaning that svn_stream_close() will not close the file. 999 * 1000 * @since New in 1.4. 1001 */ 1002svn_stream_t * 1003svn_stream_from_aprfile2(apr_file_t *file, 1004 svn_boolean_t disown, 1005 apr_pool_t *pool); 1006 1007/** Similar to svn_stream_from_aprfile2(), except that the file will 1008 * always be disowned. 1009 * 1010 * @note The stream returned is not considered to "own" the underlying 1011 * file, meaning that svn_stream_close() on the stream will not 1012 * close the file. 1013 * 1014 * @deprecated Provided for backward compatibility with the 1.3 API. 1015 */ 1016SVN_DEPRECATED 1017svn_stream_t * 1018svn_stream_from_aprfile(apr_file_t *file, 1019 apr_pool_t *pool); 1020 1021/** Set @a *in to a generic stream connected to stdin, allocated in 1022 * @a pool. The stream and its underlying APR handle will be closed 1023 * when @a pool is cleared or destroyed. 1024 * 1025 * @since New in 1.7. 1026 */ 1027svn_error_t * 1028svn_stream_for_stdin(svn_stream_t **in, 1029 apr_pool_t *pool); 1030 1031/** Set @a *err to a generic stream connected to stderr, allocated in 1032 * @a pool. The stream and its underlying APR handle will be closed 1033 * when @a pool is cleared or destroyed. 1034 * 1035 * @since New in 1.7. 1036 */ 1037svn_error_t * 1038svn_stream_for_stderr(svn_stream_t **err, 1039 apr_pool_t *pool); 1040 1041/** Set @a *out to a generic stream connected to stdout, allocated in 1042 * @a pool. The stream and its underlying APR handle will be closed 1043 * when @a pool is cleared or destroyed. 1044 */ 1045svn_error_t * 1046svn_stream_for_stdout(svn_stream_t **out, 1047 apr_pool_t *pool); 1048 1049/** Return a generic stream connected to stringbuf @a str. Allocate the 1050 * stream in @a pool. 1051 */ 1052svn_stream_t * 1053svn_stream_from_stringbuf(svn_stringbuf_t *str, 1054 apr_pool_t *pool); 1055 1056/** Return a generic read-only stream connected to string @a str. 1057 * Allocate the stream in @a pool. 1058 */ 1059svn_stream_t * 1060svn_stream_from_string(const svn_string_t *str, 1061 apr_pool_t *pool); 1062 1063/** Return a generic stream which implements buffered reads and writes. 1064 * The stream will preferentially store data in-memory, but may use 1065 * disk storage as backup if the amount of data is large. 1066 * Allocate the stream in @a result_pool 1067 * 1068 * @since New in 1.8. 1069 */ 1070svn_stream_t * 1071svn_stream_buffered(apr_pool_t *result_pool); 1072 1073/** Return a stream that decompresses all data read and compresses all 1074 * data written. The stream @a stream is used to read and write all 1075 * compressed data. All compression data structures are allocated on 1076 * @a pool. If compression support is not compiled in then 1077 * svn_stream_compressed() returns @a stream unmodified. Make sure you 1078 * call svn_stream_close() on the stream returned by this function, 1079 * so that all data are flushed and cleaned up. 1080 * 1081 * @note From 1.4, compression support is always compiled in. 1082 */ 1083svn_stream_t * 1084svn_stream_compressed(svn_stream_t *stream, 1085 apr_pool_t *pool); 1086 1087/** Return a stream that calculates checksums for all data read 1088 * and written. The stream @a stream is used to read and write all data. 1089 * The stream and the resulting digests are allocated in @a pool. 1090 * 1091 * When the stream is closed, @a *read_checksum and @a *write_checksum 1092 * are set to point to the resulting checksums, of type @a read_checksum_kind 1093 * and @a write_checksum_kind, respectively. 1094 * 1095 * Both @a read_checksum and @a write_checksum can be @c NULL, in which case 1096 * the respective checksum isn't calculated. 1097 * 1098 * If @a read_all is TRUE, make sure that all data available on @a 1099 * stream is read (and checksummed) when the stream is closed. 1100 * 1101 * Read and write operations can be mixed without interfering. 1102 * 1103 * The @a stream passed into this function is closed when the created 1104 * stream is closed. 1105 * 1106 * @since New in 1.6. 1107 */ 1108svn_stream_t * 1109svn_stream_checksummed2(svn_stream_t *stream, 1110 svn_checksum_t **read_checksum, 1111 svn_checksum_t **write_checksum, 1112 svn_checksum_kind_t checksum_kind, 1113 svn_boolean_t read_all, 1114 apr_pool_t *pool); 1115 1116/** 1117 * Similar to svn_stream_checksummed2(), but always returning the MD5 1118 * checksum in @a read_digest and @a write_digest. 1119 * 1120 * @since New in 1.4. 1121 * @deprecated Provided for backward compatibility with the 1.5 API. 1122 */ 1123SVN_DEPRECATED 1124svn_stream_t * 1125svn_stream_checksummed(svn_stream_t *stream, 1126 const unsigned char **read_digest, 1127 const unsigned char **write_digest, 1128 svn_boolean_t read_all, 1129 apr_pool_t *pool); 1130 1131/** Read from a generic stream. @see svn_stream_t. */ 1132svn_error_t * 1133svn_stream_read(svn_stream_t *stream, 1134 char *buffer, 1135 apr_size_t *len); 1136 1137/** 1138 * Skip @a len bytes from a generic @a stream. If the stream is exhausted 1139 * before @a len bytes have been read, return an error. 1140 * 1141 * @note No assumption can be made on the semantics of this function 1142 * other than that the stream read pointer will be advanced by *len 1143 * bytes. Depending on the capabilities of the underlying stream 1144 * implementation, this may for instance be translated into a sequence 1145 * of reads or a simple seek operation. If the stream implementation has 1146 * not provided a skip function, this will read from the stream and 1147 * discard the data. 1148 */ 1149svn_error_t * 1150svn_stream_skip(svn_stream_t *stream, 1151 apr_size_t len); 1152 1153/** Write to a generic stream. @see svn_stream_t. */ 1154svn_error_t * 1155svn_stream_write(svn_stream_t *stream, 1156 const char *data, 1157 apr_size_t *len); 1158 1159/** Close a generic stream. @see svn_stream_t. */ 1160svn_error_t * 1161svn_stream_close(svn_stream_t *stream); 1162 1163/** Reset a generic stream back to its origin. (E.g. On a file this would be 1164 * implemented as a seek to position 0). This function returns a 1165 * #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error when the stream doesn't 1166 * implement resetting. 1167 * 1168 * @since New in 1.7. 1169 */ 1170svn_error_t * 1171svn_stream_reset(svn_stream_t *stream); 1172 1173/** Returns @c TRUE if the generic @a stream supports svn_stream_mark(). 1174 * 1175 * @see svn_stream_mark() 1176 * @since New in 1.7. 1177 */ 1178svn_boolean_t 1179svn_stream_supports_mark(svn_stream_t *stream); 1180 1181/** Set a @a mark at the current position of a generic @a stream, 1182 * which can later be sought back to using svn_stream_seek(). 1183 * The @a mark is allocated in @a pool. 1184 * 1185 * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error 1186 * if the stream doesn't implement seeking. 1187 * 1188 * @see svn_stream_seek() 1189 * @since New in 1.7. 1190 */ 1191svn_error_t * 1192svn_stream_mark(svn_stream_t *stream, 1193 svn_stream_mark_t **mark, 1194 apr_pool_t *pool); 1195 1196/** Seek to a @a mark in a generic @a stream. 1197 * This function returns the #SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error 1198 * if the stream doesn't implement seeking. Passing NULL as @a mark, 1199 * seeks to the start of the stream. 1200 * 1201 * @see svn_stream_mark() 1202 * @since New in 1.7. 1203 */ 1204svn_error_t * 1205svn_stream_seek(svn_stream_t *stream, const svn_stream_mark_t *mark); 1206 1207/** Return a writable stream which, when written to, writes to both of the 1208 * underlying streams. Both of these streams will be closed upon closure of 1209 * the returned stream; use svn_stream_disown() if this is not the desired 1210 * behavior. One or both of @a out1 and @a out2 may be @c NULL. If both are 1211 * @c NULL, @c NULL is returned. 1212 * 1213 * @since New in 1.7. 1214 */ 1215svn_stream_t * 1216svn_stream_tee(svn_stream_t *out1, 1217 svn_stream_t *out2, 1218 apr_pool_t *pool); 1219 1220/** Write NULL-terminated string @a str to @a stream. 1221 * 1222 * @since New in 1.8. 1223 * 1224 */ 1225svn_error_t * 1226svn_stream_puts(svn_stream_t *stream, 1227 const char *str); 1228 1229/** Write to @a stream using a printf-style @a fmt specifier, passed through 1230 * apr_psprintf() using memory from @a pool. 1231 */ 1232svn_error_t * 1233svn_stream_printf(svn_stream_t *stream, 1234 apr_pool_t *pool, 1235 const char *fmt, 1236 ...) 1237 __attribute__((format(printf, 3, 4))); 1238 1239/** Write to @a stream using a printf-style @a fmt specifier, passed through 1240 * apr_psprintf() using memory from @a pool. The resulting string 1241 * will be translated to @a encoding before it is sent to @a stream. 1242 * 1243 * @note Use @c APR_LOCALE_CHARSET to translate to the encoding of the 1244 * current locale. 1245 * 1246 * @since New in 1.3. 1247 */ 1248svn_error_t * 1249svn_stream_printf_from_utf8(svn_stream_t *stream, 1250 const char *encoding, 1251 apr_pool_t *pool, 1252 const char *fmt, 1253 ...) 1254 __attribute__((format(printf, 4, 5))); 1255 1256/** Allocate @a *stringbuf in @a pool, and read into it one line (terminated 1257 * by @a eol) from @a stream. The line-terminator is read from the stream, 1258 * but is not added to the end of the stringbuf. Instead, the stringbuf 1259 * ends with a usual '\\0'. 1260 * 1261 * If @a stream runs out of bytes before encountering a line-terminator, 1262 * then set @a *eof to @c TRUE, otherwise set @a *eof to FALSE. 1263 */ 1264svn_error_t * 1265svn_stream_readline(svn_stream_t *stream, 1266 svn_stringbuf_t **stringbuf, 1267 const char *eol, 1268 svn_boolean_t *eof, 1269 apr_pool_t *pool); 1270 1271/** 1272 * Read the contents of the readable stream @a from and write them to the 1273 * writable stream @a to calling @a cancel_func before copying each chunk. 1274 * 1275 * @a cancel_func may be @c NULL. 1276 * 1277 * @note both @a from and @a to will be closed upon successful completion of 1278 * the copy (but an error may still be returned, based on trying to close 1279 * the two streams). If the closure is not desired, then you can use 1280 * svn_stream_disown() to protect either or both of the streams from 1281 * being closed. 1282 * 1283 * @since New in 1.6. 1284 */ 1285svn_error_t * 1286svn_stream_copy3(svn_stream_t *from, 1287 svn_stream_t *to, 1288 svn_cancel_func_t cancel_func, 1289 void *cancel_baton, 1290 apr_pool_t *pool); 1291 1292/** 1293 * Same as svn_stream_copy3() but the streams are not closed. 1294 * 1295 * @since New in 1.5. 1296 * @deprecated Provided for backward compatibility with the 1.5 API. 1297 */ 1298SVN_DEPRECATED 1299svn_error_t * 1300svn_stream_copy2(svn_stream_t *from, 1301 svn_stream_t *to, 1302 svn_cancel_func_t cancel_func, 1303 void *cancel_baton, 1304 apr_pool_t *pool); 1305 1306/** 1307 * Same as svn_stream_copy3(), but without the cancellation function 1308 * or stream closing. 1309 * 1310 * @since New in 1.1. 1311 * @deprecated Provided for backward compatibility with the 1.4 API. 1312 */ 1313SVN_DEPRECATED 1314svn_error_t * 1315svn_stream_copy(svn_stream_t *from, 1316 svn_stream_t *to, 1317 apr_pool_t *pool); 1318 1319 1320/** Set @a *same to TRUE if @a stream1 and @a stream2 have the same 1321 * contents, else set it to FALSE. 1322 * 1323 * Both streams will be closed before this function returns (regardless of 1324 * the result, or any possible error). 1325 * 1326 * Use @a scratch_pool for temporary allocations. 1327 * 1328 * @since New in 1.7. 1329 */ 1330svn_error_t * 1331svn_stream_contents_same2(svn_boolean_t *same, 1332 svn_stream_t *stream1, 1333 svn_stream_t *stream2, 1334 apr_pool_t *pool); 1335 1336 1337/** 1338 * Same as svn_stream_contents_same2(), but the streams will not be closed. 1339 * 1340 * @since New in 1.4. 1341 * @deprecated Provided for backward compatibility with the 1.6 API. 1342 */ 1343SVN_DEPRECATED 1344svn_error_t * 1345svn_stream_contents_same(svn_boolean_t *same, 1346 svn_stream_t *stream1, 1347 svn_stream_t *stream2, 1348 apr_pool_t *pool); 1349 1350 1351/** Read the contents of @a stream into memory, returning the data in 1352 * @a result. The stream will be closed when it has been successfully and 1353 * completely read. 1354 * 1355 * The returned memory is allocated in @a result_pool, and any temporary 1356 * allocations are performed in @a scratch_pool. 1357 * 1358 * @note due to memory pseudo-reallocation behavior (due to pools), this 1359 * can be a memory-intensive operation for large files. 1360 * 1361 * @since New in 1.6 1362 */ 1363svn_error_t * 1364svn_string_from_stream(svn_string_t **result, 1365 svn_stream_t *stream, 1366 apr_pool_t *result_pool, 1367 apr_pool_t *scratch_pool); 1368 1369 1370/** A function type provided for use as a callback from 1371 * @c svn_stream_lazyopen_create(). 1372 * 1373 * The callback function shall open a new stream and set @a *stream to 1374 * the stream object, allocated in @a result_pool. @a baton is the 1375 * callback baton that was passed to svn_stream_lazyopen_create(). 1376 * 1377 * @a result_pool is the result pool that was passed to 1378 * svn_stream_lazyopen_create(). The callback function may use 1379 * @a scratch_pool for temporary allocations; the caller may clear or 1380 * destroy @a scratch_pool any time after the function returns. 1381 * 1382 * @since New in 1.8. 1383 */ 1384typedef svn_error_t * 1385(*svn_stream_lazyopen_func_t)(svn_stream_t **stream, 1386 void *baton, 1387 apr_pool_t *result_pool, 1388 apr_pool_t *scratch_pool); 1389 1390 1391/** Return a generic stream which wraps another primary stream, 1392 * delaying the "opening" of that stream until the first time the 1393 * returned stream is accessed. 1394 * 1395 * @a open_func and @a open_baton are a callback function/baton pair 1396 * which will be invoked upon the first access of the returned 1397 * stream (read, write, mark, seek, skip, or possibly close). The 1398 * callback shall open the primary stream. 1399 * 1400 * If the only "access" the returned stream gets is to close it 1401 * then @a open_func will only be called if @a open_on_close is TRUE. 1402 * 1403 * @since New in 1.8. 1404 */ 1405svn_stream_t * 1406svn_stream_lazyopen_create(svn_stream_lazyopen_func_t open_func, 1407 void *open_baton, 1408 svn_boolean_t open_on_close, 1409 apr_pool_t *result_pool); 1410 1411/** @} */ 1412 1413/** Set @a *result to a string containing the contents of @a 1414 * filename, which is either "-" (indicating that stdin should be 1415 * read) or the utf8-encoded path of a real file. 1416 * 1417 * @warning Callers should be aware of possible unexpected results 1418 * when using this function to read from stdin where additional 1419 * stdin-reading processes abound. For example, if a program tries 1420 * both to invoke an external editor and to read from stdin, stdin 1421 * could be trashed and the editor might act funky or die outright. 1422 * 1423 * @note due to memory pseudo-reallocation behavior (due to pools), this 1424 * can be a memory-intensive operation for large files. 1425 * 1426 * @since New in 1.5. 1427 */ 1428svn_error_t * 1429svn_stringbuf_from_file2(svn_stringbuf_t **result, 1430 const char *filename, 1431 apr_pool_t *pool); 1432 1433/** Similar to svn_stringbuf_from_file2(), except that if @a filename 1434 * is "-", return the error #SVN_ERR_UNSUPPORTED_FEATURE and don't 1435 * touch @a *result. 1436 * 1437 * @deprecated Provided for backwards compatibility with the 1.4 API. 1438 */ 1439SVN_DEPRECATED 1440svn_error_t * 1441svn_stringbuf_from_file(svn_stringbuf_t **result, 1442 const char *filename, 1443 apr_pool_t *pool); 1444 1445/** Sets @a *result to a string containing the contents of the already opened 1446 * @a file. Reads from the current position in file to the end. Does not 1447 * close the file or reset the cursor position. 1448 * 1449 * @note due to memory pseudo-reallocation behavior (due to pools), this 1450 * can be a memory-intensive operation for large files. 1451 */ 1452svn_error_t * 1453svn_stringbuf_from_aprfile(svn_stringbuf_t **result, 1454 apr_file_t *file, 1455 apr_pool_t *pool); 1456 1457/** Remove file @a path, a utf8-encoded path. This wraps apr_file_remove(), 1458 * converting any error to a Subversion error. If @a ignore_enoent is TRUE, and 1459 * the file is not present (APR_STATUS_IS_ENOENT returns TRUE), then no 1460 * error will be returned. 1461 * 1462 * The file will be removed even if it is not writable. (On Windows and 1463 * OS/2, this function first clears the file's read-only bit.) 1464 * 1465 * @since New in 1.7. 1466 */ 1467svn_error_t * 1468svn_io_remove_file2(const char *path, 1469 svn_boolean_t ignore_enoent, 1470 apr_pool_t *scratch_pool); 1471 1472/** Similar to svn_io_remove_file2(), except with @a ignore_enoent set to FALSE. 1473 * 1474 * @deprecated Provided for backwards compatibility with the 1.6 API. 1475 */ 1476SVN_DEPRECATED 1477svn_error_t * 1478svn_io_remove_file(const char *path, 1479 apr_pool_t *pool); 1480 1481/** Recursively remove directory @a path. @a path is utf8-encoded. 1482 * If @a ignore_enoent is @c TRUE, don't fail if the target directory 1483 * doesn't exist. Use @a pool for temporary allocations. 1484 * 1485 * Because recursive delete of a directory tree can be a lengthy operation, 1486 * provide @a cancel_func and @a cancel_baton for interruptibility. 1487 * 1488 * @since New in 1.5. 1489 */ 1490svn_error_t * 1491svn_io_remove_dir2(const char *path, 1492 svn_boolean_t ignore_enoent, 1493 svn_cancel_func_t cancel_func, 1494 void *cancel_baton, 1495 apr_pool_t *pool); 1496 1497/** Similar to svn_io_remove_dir2(), but with @a ignore_enoent set to 1498 * @c FALSE and @a cancel_func and @a cancel_baton set to @c NULL. 1499 * 1500 * @deprecated Provided for backward compatibility with the 1.4 API 1501 */ 1502SVN_DEPRECATED 1503svn_error_t * 1504svn_io_remove_dir(const char *path, 1505 apr_pool_t *pool); 1506 1507/** Read all of the disk entries in directory @a path, a utf8-encoded 1508 * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to 1509 * undefined non-NULL values, allocated in @a pool. 1510 * 1511 * @note The `.' and `..' directories normally returned by 1512 * apr_dir_read() are NOT returned in the hash. 1513 * 1514 * @since New in 1.4. 1515 * @deprecated Provided for backward compatibility with the 1.6 API. 1516 */ 1517SVN_DEPRECATED 1518svn_error_t * 1519svn_io_get_dir_filenames(apr_hash_t **dirents, 1520 const char *path, 1521 apr_pool_t *pool); 1522 1523/** Read all of the disk entries in directory @a path, a utf8-encoded 1524 * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to 1525 * #svn_io_dirent2_t structures, allocated in @a pool. 1526 * 1527 * If @a only_check_type is set to @c TRUE, only the kind and special 1528 * fields of the svn_io_dirent2_t are filled. 1529 * 1530 * @note The `.' and `..' directories normally returned by 1531 * apr_dir_read() are NOT returned in the hash. 1532 * 1533 * @note The kind field in the @a dirents is set according to the mapping 1534 * as documented for svn_io_check_path(). 1535 * 1536 * @since New in 1.7. 1537 */ 1538svn_error_t * 1539svn_io_get_dirents3(apr_hash_t **dirents, 1540 const char *path, 1541 svn_boolean_t only_check_type, 1542 apr_pool_t *result_pool, 1543 apr_pool_t *scratch_pool); 1544 1545 1546/** Similar to svn_io_get_dirents3, but returns a mapping to svn_io_dirent_t 1547 * structures instead of svn_io_dirent2_t and with only a single pool. 1548 * 1549 * @since New in 1.3. 1550 * @deprecated Provided for backward compatibility with the 1.6 API. 1551 */ 1552SVN_DEPRECATED 1553svn_error_t * 1554svn_io_get_dirents2(apr_hash_t **dirents, 1555 const char *path, 1556 apr_pool_t *pool); 1557 1558/** Similar to svn_io_get_dirents2(), but @a *dirents is a hash table 1559 * with #svn_node_kind_t values. 1560 * 1561 * @deprecated Provided for backwards compatibility with the 1.2 API. 1562 */ 1563SVN_DEPRECATED 1564svn_error_t * 1565svn_io_get_dirents(apr_hash_t **dirents, 1566 const char *path, 1567 apr_pool_t *pool); 1568 1569/** Create a svn_io_dirent2_t instance for path. Specialized variant of 1570 * svn_io_stat() that directly translates node_kind and special. 1571 * 1572 * If @a verify_truename is @c TRUE, an additional check is performed to 1573 * verify the truename of the last path component on case insensitive 1574 * filesystems. This check is expensive compared to a just a stat, 1575 * but certainly cheaper than a full truename calculation using 1576 * apr_filepath_merge() which verifies all path components. 1577 * 1578 * If @a ignore_enoent is set to @c TRUE, set *dirent_p->kind to 1579 * svn_node_none instead of returning an error. 1580 * 1581 * @since New in 1.8. 1582 */ 1583svn_error_t * 1584svn_io_stat_dirent2(const svn_io_dirent2_t **dirent_p, 1585 const char *path, 1586 svn_boolean_t verify_truename, 1587 svn_boolean_t ignore_enoent, 1588 apr_pool_t *result_pool, 1589 apr_pool_t *scratch_pool); 1590 1591 1592/** Similar to svn_io_stat_dirent2, but always passes FALSE for 1593 * verify_truename. 1594 * 1595 * @since New in 1.7. 1596 * @deprecated Provided for backwards compatibility with the 1.7 API. 1597 */ 1598SVN_DEPRECATED 1599svn_error_t * 1600svn_io_stat_dirent(const svn_io_dirent2_t **dirent_p, 1601 const char *path, 1602 svn_boolean_t ignore_enoent, 1603 apr_pool_t *result_pool, 1604 apr_pool_t *scratch_pool); 1605 1606 1607/** Callback function type for svn_io_dir_walk() */ 1608typedef svn_error_t * (*svn_io_walk_func_t)(void *baton, 1609 const char *path, 1610 const apr_finfo_t *finfo, 1611 apr_pool_t *pool); 1612 1613/** Recursively walk the directory rooted at @a dirname, a 1614 * utf8-encoded path, invoking @a walk_func (with @a walk_baton) for 1615 * each item in the tree. For a given directory, invoke @a walk_func 1616 * on the directory itself before invoking it on any children thereof. 1617 * 1618 * Deliver to @a walk_func the information specified by @a wanted, 1619 * which is a combination of @c APR_FINFO_* flags, plus the 1620 * information specified by @c APR_FINFO_TYPE and @c APR_FINFO_NAME. 1621 * 1622 * Use @a pool for all allocations. 1623 * 1624 * @note This function does not currently pass all file types to @a 1625 * walk_func -- only APR_DIR, APR_REG, and APR_LNK. We reserve the 1626 * right to pass additional file types through this interface in the 1627 * future, though, so implementations of this callback should 1628 * explicitly test FINFO->filetype. See the APR library's 1629 * apr_filetype_e enum for the various filetypes and their meanings. 1630 * 1631 * @since New in 1.7. 1632 */ 1633svn_error_t * 1634svn_io_dir_walk2(const char *dirname, 1635 apr_int32_t wanted, 1636 svn_io_walk_func_t walk_func, 1637 void *walk_baton, 1638 apr_pool_t *pool); 1639 1640/** Similar to svn_io_dir_walk(), but only calls @a walk_func for 1641 * files of type APR_DIR (directory) and APR_REG (regular file). 1642 * 1643 * @deprecated Provided for backwards compatibility with the 1.6 API. 1644 */ 1645SVN_DEPRECATED 1646svn_error_t * 1647svn_io_dir_walk(const char *dirname, 1648 apr_int32_t wanted, 1649 svn_io_walk_func_t walk_func, 1650 void *walk_baton, 1651 apr_pool_t *pool); 1652 1653/** 1654 * Start @a cmd with @a args, using utf8-encoded @a path as working 1655 * directory. Return the process handle for the invoked program in @a 1656 * *cmd_proc. 1657 * 1658 * If @a infile_pipe is TRUE, connect @a cmd's stdin to a pipe; 1659 * otherwise, connect it to @a infile (which may be NULL). If 1660 * @a outfile_pipe is TRUE, connect @a cmd's stdout to a pipe; otherwise, 1661 * connect it to @a outfile (which may be NULL). If @a errfile_pipe 1662 * is TRUE, connect @a cmd's stderr to a pipe; otherwise, connect it 1663 * to @a errfile (which may be NULL). (Callers must pass FALSE for 1664 * each of these boolean values for which the corresponding file 1665 * handle is non-NULL.) 1666 * 1667 * @a args is a list of utf8-encoded <tt>const char *</tt> arguments, 1668 * terminated by @c NULL. @a args[0] is the name of the program, though it 1669 * need not be the same as @a cmd. 1670 * 1671 * If @a inherit is TRUE, the invoked program inherits its environment from 1672 * the caller and @a cmd, if not absolute, is searched for in PATH. 1673 * 1674 * If @a inherit is FALSE @a cmd must be an absolute path and the invoked 1675 * program inherits the environment defined by @a env or runs with an empty 1676 * environment in @a env is NULL. 1677 * 1678 * @note On some platforms, failure to execute @a cmd in the child process 1679 * will result in error output being written to @a errfile, if non-NULL, and 1680 * a non-zero exit status being returned to the parent process. 1681 * 1682 * @note An APR bug affects Windows: passing a NULL @a env does not 1683 * guarantee the invoked program to run with an empty environment when 1684 * @a inherits is FALSE, the program may inherit its parent's environment. 1685 * Explicitly pass an empty @a env to get an empty environment. 1686 * 1687 * @since New in 1.8. 1688 */ 1689svn_error_t *svn_io_start_cmd3(apr_proc_t *cmd_proc, 1690 const char *path, 1691 const char *cmd, 1692 const char *const *args, 1693 const char *const *env, 1694 svn_boolean_t inherit, 1695 svn_boolean_t infile_pipe, 1696 apr_file_t *infile, 1697 svn_boolean_t outfile_pipe, 1698 apr_file_t *outfile, 1699 svn_boolean_t errfile_pipe, 1700 apr_file_t *errfile, 1701 apr_pool_t *pool); 1702 1703 1704/** 1705 * Similar to svn_io_start_cmd3() but with @a env always set to NULL. 1706 * 1707 * @deprecated Provided for backward compatibility with the 1.7 API 1708 * @since New in 1.7. 1709 */ 1710SVN_DEPRECATED 1711svn_error_t *svn_io_start_cmd2(apr_proc_t *cmd_proc, 1712 const char *path, 1713 const char *cmd, 1714 const char *const *args, 1715 svn_boolean_t inherit, 1716 svn_boolean_t infile_pipe, 1717 apr_file_t *infile, 1718 svn_boolean_t outfile_pipe, 1719 apr_file_t *outfile, 1720 svn_boolean_t errfile_pipe, 1721 apr_file_t *errfile, 1722 apr_pool_t *pool); 1723 1724/** 1725 * Similar to svn_io_start_cmd2() but with @a infile_pipe, @a 1726 * outfile_pipe, and @a errfile_pipe always FALSE. 1727 * 1728 * @deprecated Provided for backward compatibility with the 1.6 API 1729 * @since New in 1.3. 1730 */ 1731SVN_DEPRECATED 1732svn_error_t * 1733svn_io_start_cmd(apr_proc_t *cmd_proc, 1734 const char *path, 1735 const char *cmd, 1736 const char *const *args, 1737 svn_boolean_t inherit, 1738 apr_file_t *infile, 1739 apr_file_t *outfile, 1740 apr_file_t *errfile, 1741 apr_pool_t *pool); 1742 1743/** 1744 * Wait for the process @a *cmd_proc to complete and optionally retrieve 1745 * its exit code. @a cmd is used only in error messages. 1746 * 1747 * If @a exitcode is not NULL, set @a *exitcode to the exit code of the 1748 * process and do not consider any exit code to be an error. If @a exitcode 1749 * is NULL, then if the exit code of the process is non-zero then return an 1750 * #SVN_ERR_EXTERNAL_PROGRAM error. 1751 * 1752 * If @a exitwhy is not NULL, set @a *exitwhy to indicate why the process 1753 * terminated and do not consider any reason to be an error. If @a exitwhy 1754 * is NULL, then if the termination reason is not @c APR_PROC_CHECK_EXIT() 1755 * then return an #SVN_ERR_EXTERNAL_PROGRAM error. 1756 * 1757 * @since New in 1.3. 1758 */ 1759svn_error_t * 1760svn_io_wait_for_cmd(apr_proc_t *cmd_proc, 1761 const char *cmd, 1762 int *exitcode, 1763 apr_exit_why_e *exitwhy, 1764 apr_pool_t *pool); 1765 1766/** Run a command to completion, by first calling svn_io_start_cmd() and 1767 * then calling svn_io_wait_for_cmd(). The parameters correspond to 1768 * the same-named parameters of those two functions. 1769 */ 1770svn_error_t * 1771svn_io_run_cmd(const char *path, 1772 const char *cmd, 1773 const char *const *args, 1774 int *exitcode, 1775 apr_exit_why_e *exitwhy, 1776 svn_boolean_t inherit, 1777 apr_file_t *infile, 1778 apr_file_t *outfile, 1779 apr_file_t *errfile, 1780 apr_pool_t *pool); 1781 1782/** Invoke the configured @c diff program, with @a user_args (an array 1783 * of utf8-encoded @a num_user_args arguments) if they are specified 1784 * (that is, if @a user_args is non-NULL), or "-u" if they are not. 1785 * If @a user_args is NULL, the value of @a num_user_args is ignored. 1786 * 1787 * Diff runs in utf8-encoded @a dir, and its exit status is stored in 1788 * @a exitcode, if it is not @c NULL. 1789 * 1790 * If @a label1 and/or @a label2 are not NULL they will be passed to the diff 1791 * process as the arguments of "-L" options. @a label1 and @a label2 are also 1792 * in utf8, and will be converted to native charset along with the other args. 1793 * 1794 * @a from is the first file passed to diff, and @a to is the second. The 1795 * stdout of diff will be sent to @a outfile, and the stderr to @a errfile. 1796 * 1797 * @a diff_cmd must be non-NULL. 1798 * 1799 * Do all allocation in @a pool. 1800 * @since New in 1.6.0. 1801 */ 1802svn_error_t * 1803svn_io_run_diff2(const char *dir, 1804 const char *const *user_args, 1805 int num_user_args, 1806 const char *label1, 1807 const char *label2, 1808 const char *from, 1809 const char *to, 1810 int *exitcode, 1811 apr_file_t *outfile, 1812 apr_file_t *errfile, 1813 const char *diff_cmd, 1814 apr_pool_t *pool); 1815 1816/** Similar to svn_io_run_diff2() but with @a diff_cmd encoded in internal 1817 * encoding used by APR. 1818 * 1819 * @deprecated Provided for backwards compatibility with the 1.5 API. */ 1820SVN_DEPRECATED 1821svn_error_t * 1822svn_io_run_diff(const char *dir, 1823 const char *const *user_args, 1824 int num_user_args, 1825 const char *label1, 1826 const char *label2, 1827 const char *from, 1828 const char *to, 1829 int *exitcode, 1830 apr_file_t *outfile, 1831 apr_file_t *errfile, 1832 const char *diff_cmd, 1833 apr_pool_t *pool); 1834 1835 1836 1837/** Invoke the configured @c diff3 program, in utf8-encoded @a dir 1838 * like this: 1839 * 1840 * diff3 -E -m @a mine @a older @a yours > @a merged 1841 * 1842 * (See the diff3 documentation for details.) 1843 * 1844 * If @a user_args is non-NULL, replace "-E" with the <tt>const char*</tt> 1845 * elements that @a user_args contains. 1846 * 1847 * @a mine, @a older and @a yours are utf8-encoded paths (relative to 1848 * @a dir or absolute) to three files that already exist. 1849 * 1850 * @a merged is an open file handle, and is left open after the merge 1851 * result is written to it. (@a merged should *not* be the same file 1852 * as @a mine, or nondeterministic things may happen!) 1853 * 1854 * @a mine_label, @a older_label, @a yours_label are utf8-encoded label 1855 * parameters for diff3's -L option. Any of them may be @c NULL, in 1856 * which case the corresponding @a mine, @a older, or @a yours parameter is 1857 * used instead. 1858 * 1859 * Set @a *exitcode to diff3's exit status. If @a *exitcode is anything 1860 * other than 0 or 1, then return #SVN_ERR_EXTERNAL_PROGRAM. (Note the 1861 * following from the diff3 info pages: "An exit status of 0 means 1862 * `diff3' was successful, 1 means some conflicts were found, and 2 1863 * means trouble.") 1864 * 1865 * @a diff3_cmd must be non-NULL. 1866 * 1867 * Do all allocation in @a pool. 1868 * 1869 * @since New in 1.4. 1870 */ 1871svn_error_t * 1872svn_io_run_diff3_3(int *exitcode, 1873 const char *dir, 1874 const char *mine, 1875 const char *older, 1876 const char *yours, 1877 const char *mine_label, 1878 const char *older_label, 1879 const char *yours_label, 1880 apr_file_t *merged, 1881 const char *diff3_cmd, 1882 const apr_array_header_t *user_args, 1883 apr_pool_t *pool); 1884 1885/** Similar to svn_io_run_diff3_3(), but with @a diff3_cmd encoded in 1886 * internal encoding used by APR. 1887 * 1888 * @deprecated Provided for backwards compatibility with the 1.5 API. 1889 * @since New in 1.4. 1890 */ 1891SVN_DEPRECATED 1892svn_error_t * 1893svn_io_run_diff3_2(int *exitcode, 1894 const char *dir, 1895 const char *mine, 1896 const char *older, 1897 const char *yours, 1898 const char *mine_label, 1899 const char *older_label, 1900 const char *yours_label, 1901 apr_file_t *merged, 1902 const char *diff3_cmd, 1903 const apr_array_header_t *user_args, 1904 apr_pool_t *pool); 1905 1906/** Similar to svn_io_run_diff3_2(), but with @a user_args set to @c NULL. 1907 * 1908 * @deprecated Provided for backwards compatibility with the 1.3 API. 1909 */ 1910SVN_DEPRECATED 1911svn_error_t * 1912svn_io_run_diff3(const char *dir, 1913 const char *mine, 1914 const char *older, 1915 const char *yours, 1916 const char *mine_label, 1917 const char *older_label, 1918 const char *yours_label, 1919 apr_file_t *merged, 1920 int *exitcode, 1921 const char *diff3_cmd, 1922 apr_pool_t *pool); 1923 1924 1925/** Parse utf8-encoded @a mimetypes_file as a MIME types file (such as 1926 * is provided with Apache HTTP Server), and set @a *type_map to a 1927 * hash mapping <tt>const char *</tt> filename extensions to 1928 * <tt>const char *</tt> MIME types. 1929 * 1930 * @since New in 1.5. 1931 */ 1932svn_error_t * 1933svn_io_parse_mimetypes_file(apr_hash_t **type_map, 1934 const char *mimetypes_file, 1935 apr_pool_t *pool); 1936 1937 1938/** Examine utf8-encoded @a file to determine if it can be described by a 1939 * known (as in, known by this function) Multipurpose Internet Mail 1940 * Extension (MIME) type. If so, set @a *mimetype to a character string 1941 * describing the MIME type, else set it to @c NULL. 1942 * 1943 * If not @c NULL, @a mimetype_map is a hash mapping <tt>const char *</tt> 1944 * filename extensions to <tt>const char *</tt> MIME types, and is the 1945 * first source consulted regarding @a file's MIME type. 1946 * 1947 * Use @a pool for any necessary allocations. 1948 * 1949 * @since New in 1.5. 1950 */ 1951svn_error_t * 1952svn_io_detect_mimetype2(const char **mimetype, 1953 const char *file, 1954 apr_hash_t *mimetype_map, 1955 apr_pool_t *pool); 1956 1957 1958/** Like svn_io_detect_mimetype2, but with @a mimetypes_map set to 1959 * @c NULL. 1960 * 1961 * @deprecated Provided for backward compatibility with the 1.4 API 1962 */ 1963SVN_DEPRECATED 1964svn_error_t * 1965svn_io_detect_mimetype(const char **mimetype, 1966 const char *file, 1967 apr_pool_t *pool); 1968 1969 1970/** Examine up to @a len bytes of data in @a buf to determine if the 1971 * can be considered binary data, in which case return TRUE. 1972 * If the data can be considered plain-text data, return FALSE. 1973 * 1974 * @since New in 1.7. 1975 */ 1976svn_boolean_t 1977svn_io_is_binary_data(const void *buf, apr_size_t len); 1978 1979 1980/** Wrapper for apr_file_open(). @a fname is utf8-encoded. 1981 Always passed flag | APR_BINARY to apr. */ 1982svn_error_t * 1983svn_io_file_open(apr_file_t **new_file, 1984 const char *fname, 1985 apr_int32_t flag, 1986 apr_fileperms_t perm, 1987 apr_pool_t *pool); 1988 1989 1990/** Wrapper for apr_file_close(). */ 1991svn_error_t * 1992svn_io_file_close(apr_file_t *file, 1993 apr_pool_t *pool); 1994 1995 1996/** Wrapper for apr_file_getc(). */ 1997svn_error_t * 1998svn_io_file_getc(char *ch, 1999 apr_file_t *file, 2000 apr_pool_t *pool); 2001 2002 2003/** Wrapper for apr_file_putc(). 2004 * @since New in 1.7 2005 */ 2006svn_error_t * 2007svn_io_file_putc(char ch, 2008 apr_file_t *file, 2009 apr_pool_t *pool); 2010 2011 2012/** Wrapper for apr_file_info_get(). */ 2013svn_error_t * 2014svn_io_file_info_get(apr_finfo_t *finfo, 2015 apr_int32_t wanted, 2016 apr_file_t *file, 2017 apr_pool_t *pool); 2018 2019 2020/** Wrapper for apr_file_read(). */ 2021svn_error_t * 2022svn_io_file_read(apr_file_t *file, 2023 void *buf, 2024 apr_size_t *nbytes, 2025 apr_pool_t *pool); 2026 2027 2028/** Wrapper for apr_file_read_full(). 2029 * 2030 * If @a hit_eof is not NULL, EOF will be indicated there and no 2031 * svn_error_t error object will be created upon EOF. 2032 * 2033 * @since New in 1.7 2034 */ 2035svn_error_t * 2036svn_io_file_read_full2(apr_file_t *file, 2037 void *buf, 2038 apr_size_t nbytes, 2039 apr_size_t *bytes_read, 2040 svn_boolean_t *hit_eof, 2041 apr_pool_t *pool); 2042 2043 2044/** Similar to svn_io_file_read_full2 with hit_eof being set 2045 * to @c NULL. 2046 * 2047 * @deprecated Provided for backward compatibility with the 1.6 API 2048 */ 2049SVN_DEPRECATED 2050svn_error_t * 2051svn_io_file_read_full(apr_file_t *file, 2052 void *buf, 2053 apr_size_t nbytes, 2054 apr_size_t *bytes_read, 2055 apr_pool_t *pool); 2056 2057 2058/** Wrapper for apr_file_seek(). */ 2059svn_error_t * 2060svn_io_file_seek(apr_file_t *file, 2061 apr_seek_where_t where, 2062 apr_off_t *offset, 2063 apr_pool_t *pool); 2064 2065 2066/** Wrapper for apr_file_write(). */ 2067svn_error_t * 2068svn_io_file_write(apr_file_t *file, 2069 const void *buf, 2070 apr_size_t *nbytes, 2071 apr_pool_t *pool); 2072 2073 2074/** Wrapper for apr_file_write_full(). */ 2075svn_error_t * 2076svn_io_file_write_full(apr_file_t *file, 2077 const void *buf, 2078 apr_size_t nbytes, 2079 apr_size_t *bytes_written, 2080 apr_pool_t *pool); 2081 2082/** 2083 * Open a unique file in @a dirpath, and write @a nbytes from @a buf to 2084 * the file before flushing it to disk and closing it. Return the name 2085 * of the newly created file in @a *tmp_path, allocated in @a pool. 2086 * 2087 * If @a dirpath is @c NULL, use the path returned from svn_io_temp_dir(). 2088 * (Note that when using the system-provided temp directory, it may not 2089 * be possible to atomically rename the resulting file due to cross-device 2090 * issues.) 2091 * 2092 * The file will be deleted according to @a delete_when. 2093 * 2094 * @since New in 1.6. 2095 */ 2096svn_error_t * 2097svn_io_write_unique(const char **tmp_path, 2098 const char *dirpath, 2099 const void *buf, 2100 apr_size_t nbytes, 2101 svn_io_file_del_t delete_when, 2102 apr_pool_t *pool); 2103 2104/** Wrapper for apr_file_trunc(). 2105 * @since New in 1.6. */ 2106svn_error_t * 2107svn_io_file_trunc(apr_file_t *file, 2108 apr_off_t offset, 2109 apr_pool_t *pool); 2110 2111 2112/** Wrapper for apr_stat(). @a fname is utf8-encoded. */ 2113svn_error_t * 2114svn_io_stat(apr_finfo_t *finfo, 2115 const char *fname, 2116 apr_int32_t wanted, 2117 apr_pool_t *pool); 2118 2119 2120/** Rename and/or move the node (not necessarily a regular file) at 2121 * @a from_path to a new path @a to_path within the same filesystem. 2122 * In some cases, an existing node at @a to_path will be overwritten. 2123 * 2124 * A wrapper for apr_file_rename(). @a from_path and @a to_path are 2125 * utf8-encoded. 2126 */ 2127svn_error_t * 2128svn_io_file_rename(const char *from_path, 2129 const char *to_path, 2130 apr_pool_t *pool); 2131 2132 2133/** Move the file from @a from_path to @a to_path, even across device 2134 * boundaries. Overwrite @a to_path if it exists. 2135 * 2136 * @note This function is different from svn_io_file_rename in that the 2137 * latter fails in the 'across device boundaries' case. 2138 * 2139 * @since New in 1.3. 2140 */ 2141svn_error_t * 2142svn_io_file_move(const char *from_path, 2143 const char *to_path, 2144 apr_pool_t *pool); 2145 2146 2147/** Wrapper for apr_dir_make(). @a path is utf8-encoded. */ 2148svn_error_t * 2149svn_io_dir_make(const char *path, 2150 apr_fileperms_t perm, 2151 apr_pool_t *pool); 2152 2153/** Same as svn_io_dir_make(), but sets the hidden attribute on the 2154 directory on systems that support it. */ 2155svn_error_t * 2156svn_io_dir_make_hidden(const char *path, 2157 apr_fileperms_t perm, 2158 apr_pool_t *pool); 2159 2160/** 2161 * Same as svn_io_dir_make(), but attempts to set the sgid on the 2162 * directory on systems that support it. Does not return an error if 2163 * the attempt to set the sgid bit fails. On Unix filesystems, 2164 * setting the sgid bit on a directory ensures that files and 2165 * subdirectories created within inherit group ownership from the 2166 * parent instead of from the primary gid. 2167 * 2168 * @since New in 1.1. 2169 */ 2170svn_error_t * 2171svn_io_dir_make_sgid(const char *path, 2172 apr_fileperms_t perm, 2173 apr_pool_t *pool); 2174 2175/** Wrapper for apr_dir_open(). @a dirname is utf8-encoded. */ 2176svn_error_t * 2177svn_io_dir_open(apr_dir_t **new_dir, 2178 const char *dirname, 2179 apr_pool_t *pool); 2180 2181/** Wrapper for apr_dir_close(). 2182 * 2183 * @since New in 1.7. 2184 */ 2185svn_error_t * 2186svn_io_dir_close(apr_dir_t *thedir); 2187 2188/** Wrapper for apr_dir_remove(). @a dirname is utf8-encoded. 2189 * @note This function has this name to avoid confusion with 2190 * svn_io_remove_dir2(), which is recursive. 2191 */ 2192svn_error_t * 2193svn_io_dir_remove_nonrecursive(const char *dirname, 2194 apr_pool_t *pool); 2195 2196 2197/** Wrapper for apr_dir_read(). Ensures that @a finfo->name is 2198 * utf8-encoded, which means allocating @a finfo->name in @a pool, 2199 * which may or may not be the same as @a finfo's pool. Use @a pool 2200 * for error allocation as well. 2201 */ 2202svn_error_t * 2203svn_io_dir_read(apr_finfo_t *finfo, 2204 apr_int32_t wanted, 2205 apr_dir_t *thedir, 2206 apr_pool_t *pool); 2207 2208/** Wrapper for apr_file_name_get(). @a *filename is utf8-encoded. 2209 * 2210 * @note The file name may be NULL. 2211 * 2212 * @since New in 1.7. */ 2213svn_error_t * 2214svn_io_file_name_get(const char **filename, 2215 apr_file_t *file, 2216 apr_pool_t *pool); 2217 2218 2219 2220/** Version/format files. 2221 * 2222 * @defgroup svn_io_format_files Version/format files 2223 * @{ 2224 */ 2225 2226/** Set @a *version to the integer that starts the file at @a path. If the 2227 * file does not begin with a series of digits followed by a newline, 2228 * return the error #SVN_ERR_BAD_VERSION_FILE_FORMAT. Use @a pool for 2229 * all allocations. 2230 */ 2231svn_error_t * 2232svn_io_read_version_file(int *version, 2233 const char *path, 2234 apr_pool_t *pool); 2235 2236/** Create (or overwrite) the file at @a path with new contents, 2237 * formatted as a non-negative integer @a version followed by a single 2238 * newline. On successful completion the file will be read-only. Use 2239 * @a pool for all allocations. 2240 */ 2241svn_error_t * 2242svn_io_write_version_file(const char *path, 2243 int version, 2244 apr_pool_t *pool); 2245 2246/** Read a line of text from a file, up to a specified length. 2247 * 2248 * Allocate @a *stringbuf in @a result_pool, and read into it one line 2249 * from @a file. Reading stops either after a line-terminator was found 2250 * or after @a max_len bytes have been read. 2251 * 2252 * If end-of-file is reached or @a max_len bytes have been read, and @a eof 2253 * is not NULL, then set @a *eof to @c TRUE. 2254 * 2255 * The line-terminator is not stored in @a *stringbuf. 2256 * The line-terminator is detected automatically and stored in @a *eol 2257 * if @a eol is not NULL. If EOF is reached and @a file does not end 2258 * with a newline character, and @a eol is not NULL, @ *eol is set to NULL. 2259 * 2260 * @a scratch_pool is used for temporary allocations. 2261 * 2262 * Hint: To read all data until a line-terminator is hit, pass APR_SIZE_MAX 2263 * for @a max_len. 2264 * 2265 * @since New in 1.8. 2266 */ 2267svn_error_t * 2268svn_io_file_readline(apr_file_t *file, 2269 svn_stringbuf_t **stringbuf, 2270 const char **eol, 2271 svn_boolean_t *eof, 2272 apr_size_t max_len, 2273 apr_pool_t *result_pool, 2274 apr_pool_t *scratch_pool); 2275 2276/** @} */ 2277 2278#ifdef __cplusplus 2279} 2280#endif /* __cplusplus */ 2281 2282#endif /* SVN_IO_H */ 2283