subversion-1.9.7HEADsubversion-1.9.7master

1 files changed, 218 insertions, 12 deletions

diff --git a/subversion/include/svn_io.h b/subversion/include/svn_io.h
index 0082917..42eb422 100644
--- a/subversion/include/svn_io.h
+++ b/subversion/include/svn_io.h
@@ -682,8 +682,15 @@ svn_io_files_contents_three_same_p(svn_boolean_t *same12,
                                    const char *file3,
                                    apr_pool_t *scratch_pool);
 
-/** Create file at utf8-encoded @a file with contents @a contents.
- * @a file must not already exist.
+/** Create a file at utf8-encoded path @a file with the contents given
+ * by the null-terminated string @a contents.
+ *
+ * @a file must not already exist. If an error occurs while writing or
+ * closing the file, attempt to delete the file before returning the error.
+ *
+ * Write the data in 'binary' mode (#APR_FOPEN_BINARY). If @a contents
+ * is @c NULL, create an empty file.
+ *
  * Use @a pool for memory allocations.
  */
 svn_error_t *
@@ -691,6 +698,38 @@ svn_io_file_create(const char *file,
                    const char *contents,
                    apr_pool_t *pool);
 
+/** Create a file at utf8-encoded path @a file with the contents given
+ * by @a contents of @a length bytes.
+ *
+ * @a file must not already exist. If an error occurs while writing or
+ * closing the file, attempt to delete the file before returning the error.
+ *
+ * Write the data in 'binary' mode (#APR_FOPEN_BINARY). If @a length is
+ * zero, create an empty file; in this case @a contents may be @c NULL.
+ *
+ * Use @a scratch_pool for temporary allocations.
+ *
+ * @since New in 1.9.
+ */
+svn_error_t *
+svn_io_file_create_bytes(const char *file,
+                         const void *contents,
+                         apr_size_t length,
+                         apr_pool_t *scratch_pool);
+
+/** Create an empty file at utf8-encoded path @a file.
+ *
+ * @a file must not already exist. If an error occurs while
+ * closing the file, attempt to delete the file before returning the error.
+ *
+ * Use @a scratch_pool for temporary allocations.
+ *
+ * @since New in 1.9.
+ */
+svn_error_t *
+svn_io_file_create_empty(const char *file,
+                         apr_pool_t *scratch_pool);
+
 /**
  * Lock file at @a lock_file. If @a exclusive is TRUE,
  * obtain exclusive lock, otherwise obtain shared lock.
@@ -759,6 +798,12 @@ svn_io_unlock_open_file(apr_file_t *lockfile_handle,
  * Flush any unwritten data from @a file to disk.  Use @a pool for
  * memory allocations.
  *
+ * @note This function uses advanced file control operations to flush buffers
+ * to disk that aren't always accessible and can be very expensive on systems
+ * that implement flushing on all IO layers, like Windows. Please avoid using
+ * this function in cases where the file should just work on any network
+ * filesystem. In many cases a normal svn_io_file_flush() will work just fine.
+ *
  * @since New in 1.1.
  */
 svn_error_t *
@@ -804,14 +849,16 @@ svn_io_dir_file_copy(const char *src_path,
  * On entry to the handler, the pointed-to value should be the amount
  * of data which can be read or the amount of data to write.  When the
  * handler returns, the value is reset to the amount of data actually
- * read or written.  Handlers are obliged to complete a read or write
- * to the maximum extent possible; thus, a short read with no
- * associated error implies the end of the input stream, and a short
- * write should never occur without an associated error.
+ * read or written.  The write and full read handler are obliged to
+ * complete a read or write to the maximum extent possible; thus, a
+ * short read with no associated error implies the end of the input
+ * stream, and a short write should never occur without an associated
+ * error. In Subversion 1.9 the stream api was extended to also support
+ * limited reads via the new svn_stream_read2() api.
  *
- * In Subversion 1.7 reset support was added as an optional feature of
- * streams. If a stream implements resetting it allows reading the data
- * again after a successful call to svn_stream_reset().
+ * In Subversion 1.7 mark, seek and reset support was added as an optional
+ * feature of streams. If a stream implements resetting it allows reading
+ * the data again after a successful call to svn_stream_reset().
  */
 typedef struct svn_stream_t svn_stream_t;
 
@@ -861,7 +908,15 @@ typedef svn_error_t *(*svn_stream_mark_fn_t)(void *baton,
  * @since New in 1.7.
  */
 typedef svn_error_t *(*svn_stream_seek_fn_t)(void *baton,
-                                         const svn_stream_mark_t *mark);
+                                             const svn_stream_mark_t *mark);
+
+/** Poll handler for generic streams that support incomplete reads, @see
+ * svn_stream_t and svn_stream_data_available().
+ *
+ * @since New in 1.9.
+ */
+typedef svn_error_t *(*svn_stream_data_available_fn_t)(void *baton,
+                                              svn_boolean_t *data_available);
 
 /** Create a generic stream.  @see svn_stream_t. */
 svn_stream_t *
@@ -873,7 +928,24 @@ void
 svn_stream_set_baton(svn_stream_t *stream,
                      void *baton);
 
-/** Set @a stream's read function to @a read_fn */
+/** Set @a stream's read functions to @a read_fn and @a read_full_fn. If
+ * @a read_full_fn is NULL a default implementation based on multiple calls
+ * to @a read_fn will be used.
+ *
+ * @since New in 1.9.
+ */
+void
+svn_stream_set_read2(svn_stream_t *stream,
+                     svn_read_fn_t read_fn,
+                     svn_read_fn_t read_full_fn);
+
+/** Set @a stream's read function to @a read_fn.
+ *
+ * This function sets only the full read function to read_fn.
+ *
+ * @deprecated Provided for backward compatibility with the 1.8 API.
+ */
+SVN_DEPRECATED
 void
 svn_stream_set_read(svn_stream_t *stream,
                     svn_read_fn_t read_fn);
@@ -912,6 +984,14 @@ void
 svn_stream_set_seek(svn_stream_t *stream,
                     svn_stream_seek_fn_t seek_fn);
 
+/** Set @a stream's data available function to @a data_available_fn
+ *
+ * @since New in 1.9.
+ */
+void
+svn_stream_set_data_available(svn_stream_t *stream,
+                              svn_stream_data_available_fn_t data_available);
+
 /** Create a stream that is empty for reading and infinite for writing. */
 svn_stream_t *
 svn_stream_empty(apr_pool_t *pool);
@@ -1049,6 +1129,20 @@ svn_error_t *
 svn_stream_for_stdout(svn_stream_t **out,
                       apr_pool_t *pool);
 
+/** Set @a *str to a string buffer allocated in @a result_pool that contains
+ * all data from the current position in @a stream to its end.  @a len_hint
+ * specifies the initial capacity of the string buffer and may be 0.  The
+ * buffer gets automatically resized to fit the actual amount of data being
+ * read from @a stream.
+ *
+ * @since New in 1.9.
+ */
+svn_error_t *
+svn_stringbuf_from_stream(svn_stringbuf_t **str,
+                          svn_stream_t *stream,
+                          apr_size_t len_hint,
+                          apr_pool_t *result_pool);
+
 /** Return a generic stream connected to stringbuf @a str.  Allocate the
  * stream in @a pool.
  */
@@ -1131,7 +1225,48 @@ svn_stream_checksummed(svn_stream_t *stream,
                        svn_boolean_t read_all,
                        apr_pool_t *pool);
 
-/** Read from a generic stream. @see svn_stream_t. */
+/** Read from a generic stream until @a buffer is filled upto @a *len or
+ * until EOF is reached. @see svn_stream_t
+ *
+ * @since New in 1.9.
+ */
+svn_error_t *
+svn_stream_read_full(svn_stream_t *stream,
+                     char *buffer,
+                     apr_size_t *len);
+
+
+/** Returns @c TRUE if the generic @c stream supports svn_stream_read2().
+ *
+ * @since New in 1.9.
+ */
+svn_boolean_t
+svn_stream_supports_partial_read(svn_stream_t *stream);
+
+/** Read all currently available upto @a *len into @a buffer. Use
+ * svn_stream_read_full() if you want to wait for the buffer to be filled
+ * or EOF. If the stream doesn't support limited reads this function will
+ * return an #SVN_ERR_STREAM_NOT_SUPPORTED error.
+ *
+ * A 0 byte read signals the end of the stream.
+ *
+ * @since New in 1.9.
+ */
+svn_error_t *
+svn_stream_read2(svn_stream_t *stream,
+                 char *buffer,
+                 apr_size_t *len);
+
+
+/** Read from a generic stream until the buffer is completely filled or EOF.
+ * @see svn_stream_t.
+ *
+ * @note This function is a wrapper of svn_stream_read_full() now, which name
+ * better documents the behavior of this function.
+ *
+ * @deprecated Provided for backward compatibility with the 1.8 API
+ */
+SVN_DEPRECATED
 svn_error_t *
 svn_stream_read(svn_stream_t *stream,
                 char *buffer,
@@ -1209,6 +1344,20 @@ svn_stream_mark(svn_stream_t *stream,
 svn_error_t *
 svn_stream_seek(svn_stream_t *stream, const svn_stream_mark_t *mark);
 
+/** When a stream supports polling for available data, obtain a boolean
+ * indicating whether data is waiting to be read. If the stream doesn't
+ * support polling this function returns a #SVN_ERR_STREAM_NOT_SUPPORTED
+ * error.
+ *
+ * If the data_available callback is implemented and the stream is at the end
+ * the stream will set @a *data_available to FALSE.
+ *
+ * @since New in 1.9.
+ */
+svn_error_t *
+svn_stream_data_available(svn_stream_t *stream,
+                          svn_boolean_t *data_available);
+
 /** Return a writable stream which, when written to, writes to both of the
  * underlying streams.  Both of these streams will be closed upon closure of
  * the returned stream; use svn_stream_disown() if this is not the desired
@@ -1405,6 +1554,10 @@ typedef svn_error_t *
  * If the only "access" the returned stream gets is to close it
  * then @a open_func will only be called if @a open_on_close is TRUE.
  *
+ * Allocate the returned stream in @a result_pool. Also arrange for
+ * @a result_pool to be passed as the @c result_pool parameter to
+ * @a open_func when it is called.
+ *
  * @since New in 1.8.
  */
 svn_stream_t *
@@ -2067,6 +2220,28 @@ svn_io_file_seek(apr_file_t *file,
                  apr_off_t *offset,
                  apr_pool_t *pool);
 
+/** Set the file pointer of the #APR_BUFFERED @a file to @a offset.  In
+ * contrast to #svn_io_file_seek, this function will attempt to resize the
+ * internal data buffer to @a block_size bytes and to read data aligned to
+ * multiples of that value.  The beginning of the block will be returned
+ * in @a buffer_start, if that is not NULL.
+ * Uses @a scratch_pool for temporary allocations.
+ *
+ * @note Due to limitations of the APR API, the alignment may not be
+ * successful.  If you never use any other seek function on @a file,
+ * however, you are virtually guaranteed to get at least 4kByte alignment
+ * for all reads.
+ *
+ * @note Calling this for non-buffered files is legal but inefficient.
+ *
+ * @since New in 1.9
+ */
+svn_error_t *
+svn_io_file_aligned_seek(apr_file_t *file,
+                         apr_off_t block_size,
+                         apr_off_t *buffer_start,
+                         apr_off_t offset,
+                         apr_pool_t *scratch_pool);
 
 /** Wrapper for apr_file_write(). */
 svn_error_t *
@@ -2075,6 +2250,14 @@ svn_io_file_write(apr_file_t *file,
                   apr_size_t *nbytes,
                   apr_pool_t *pool);
 
+/** Wrapper for apr_file_flush().
+ * @since New in 1.9
+ */
+svn_error_t *
+svn_io_file_flush(apr_file_t *file,
+                  apr_pool_t *scratch_pool);
+
+
 
 /** Wrapper for apr_file_write_full(). */
 svn_error_t *
@@ -2085,6 +2268,29 @@ svn_io_file_write_full(apr_file_t *file,
                        apr_pool_t *pool);
 
 /**
+ * Writes @a nbytes bytes from @a *buf to a temporary file inside the same
+ * directory as @a *final_path. Then syncs the temporary file to disk and
+ * closes the file. After this rename the temporary file to @a final_path,
+ * possibly replacing an existing file.
+ *
+ * If @a copy_perms_path is not NULL, copy the permissions applied on @a
+ * @a copy_perms_path on the temporary file before renaming.
+ *
+ * @note This function uses advanced file control operations to flush buffers
+ * to disk that aren't always accessible and can be very expensive. Avoid
+ * using this function in cases where the file should just work on any
+ * network filesystem.
+ *
+ * @since New in 1.9.
+ */
+svn_error_t *
+svn_io_write_atomic(const char *final_path,
+                    const void *buf,
+                    apr_size_t nbytes,
+                    const char* copy_perms_path,
+                    apr_pool_t *scratch_pool);
+
+/**
  * Open a unique file in @a dirpath, and write @a nbytes from @a buf to
  * the file before flushing it to disk and closing it.  Return the name
  * of the newly created file in @a *tmp_path, allocated in @a pool.