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