Generic byte-streams. More...

Typedefs
typedef struct svn_stream_t	svn_stream_t
	An abstract stream of bytes--either incoming or outgoing or both.
typedef svn_error_t (	svn_read_fn_t )(void baton, char buffer, apr_size_t *len)
	Read handler function for a generic stream.
typedef svn_error_t (	svn_stream_skip_fn_t )(void *baton, apr_size_t len)
	Skip data handler function for a generic stream.
typedef svn_error_t (	svn_write_fn_t )(void baton, const char data, apr_size_t *len)
	Write handler function for a generic stream.
typedef svn_error_t (	svn_close_fn_t )(void *baton)
	Close handler function for a generic stream.
typedef struct svn_stream_mark_t	svn_stream_mark_t
	An opaque type which represents a mark on a stream.
typedef svn_error_t (	svn_stream_mark_fn_t )(void baton, svn_stream_mark_t mark, apr_pool_t pool)
	Mark handler function for a generic stream.
typedef svn_error_t (	svn_stream_seek_fn_t )(void baton, const svn_stream_mark_t mark)
	Seek handler function for a generic stream.
Functions
svn_stream_t *	svn_stream_create (void baton, apr_pool_t pool)
	Create a generic stream.
void	svn_stream_set_baton (svn_stream_t stream, void baton)
	Set stream's baton to baton.
void	svn_stream_set_read (svn_stream_t *stream, svn_read_fn_t read_fn)
	Set stream's read function to read_fn.
void	svn_stream_set_skip (svn_stream_t *stream, svn_stream_skip_fn_t skip_fn)
	Set stream's skip function to skip_fn.
void	svn_stream_set_write (svn_stream_t *stream, svn_write_fn_t write_fn)
	Set stream's write function to write_fn.
void	svn_stream_set_close (svn_stream_t *stream, svn_close_fn_t close_fn)
	Set stream's close function to close_fn.
void	svn_stream_set_mark (svn_stream_t *stream, svn_stream_mark_fn_t mark_fn)
	Set stream's mark function to mark_fn.
void	svn_stream_set_seek (svn_stream_t *stream, svn_stream_seek_fn_t seek_fn)
	Set stream's seek function to seek_fn.
svn_stream_t *	svn_stream_empty (apr_pool_t *pool)
	Create a stream that is empty for reading and infinite for writing.
svn_stream_t *	svn_stream_disown (svn_stream_t stream, apr_pool_t pool)
	Return a stream allocated in pool which forwards all requests to stream.
svn_error_t *	svn_stream_open_readonly (svn_stream_t *stream, const char path, apr_pool_t result_pool, apr_pool_t scratch_pool)
	Create a stream to read the file at path.
svn_error_t *	svn_stream_open_writable (svn_stream_t *stream, const char path, apr_pool_t result_pool, apr_pool_t scratch_pool)
	Create a stream to write a file at path.
svn_error_t *	svn_stream_open_unique (svn_stream_t stream, const char temp_path, const char dirpath, svn_io_file_del_t delete_when, apr_pool_t result_pool, apr_pool_t *scratch_pool)
	Create a writable stream to a file in the directory dirpath.
svn_stream_t *	svn_stream_from_aprfile2 (apr_file_t file, svn_boolean_t disown, apr_pool_t pool)
	Create a stream from an APR file.
svn_stream_t *	svn_stream_from_aprfile (apr_file_t file, apr_pool_t pool)
	Similar to svn_stream_from_aprfile2(), except that the file will always be disowned.
svn_error_t *	svn_stream_for_stdin (svn_stream_t *in, apr_pool_t pool)
	Set in to a generic stream connected to stdin, allocated in pool*.
svn_error_t *	svn_stream_for_stderr (svn_stream_t *err, apr_pool_t pool)
	Set err to a generic stream connected to stderr, allocated in pool*.
svn_error_t *	svn_stream_for_stdout (svn_stream_t *out, apr_pool_t pool)
	Set out to a generic stream connected to stdout, allocated in pool*.
svn_stream_t *	svn_stream_from_stringbuf (svn_stringbuf_t str, apr_pool_t pool)
	Return a generic stream connected to stringbuf str.
svn_stream_t *	svn_stream_from_string (const svn_string_t str, apr_pool_t pool)
	Return a generic read-only stream connected to string str.
svn_stream_t *	svn_stream_compressed (svn_stream_t stream, apr_pool_t pool)
	Return a stream that decompresses all data read and compresses all data written.
svn_stream_t *	svn_stream_checksummed2 (svn_stream_t stream, svn_checksum_t read_checksum, svn_checksum_t write_checksum, svn_checksum_kind_t checksum_kind, svn_boolean_t read_all, apr_pool_t pool)
	Return a stream that calculates checksums for all data read and written.
svn_stream_t *	svn_stream_checksummed (svn_stream_t stream, const unsigned char read_digest, const unsigned char write_digest, svn_boolean_t read_all, apr_pool_t pool)
	Similar to svn_stream_checksummed2(), but always returning the MD5 checksum in read_digest and write_digest.
svn_error_t *	svn_stream_read (svn_stream_t stream, char buffer, apr_size_t *len)
	Read from a generic stream.
svn_error_t *	svn_stream_skip (svn_stream_t *stream, apr_size_t len)
	Skip len bytes from a generic stream.
svn_error_t *	svn_stream_write (svn_stream_t stream, const char data, apr_size_t *len)
	Write to a generic stream.
svn_error_t *	svn_stream_close (svn_stream_t *stream)
	Close a generic stream.
svn_error_t *	svn_stream_reset (svn_stream_t *stream)
	Reset a generic stream back to its origin.
svn_boolean_t	svn_stream_supports_mark (svn_stream_t *stream)
	Returns `TRUE` if the generic stream supports svn_stream_mark().
svn_error_t *	svn_stream_mark (svn_stream_t stream, svn_stream_mark_t mark, apr_pool_t pool)
	Set a mark at the current position of a generic stream, which can later be sought back to using svn_stream_seek().
svn_error_t *	svn_stream_seek (svn_stream_t stream, const svn_stream_mark_t mark)
	Seek to a mark in a generic stream.
svn_stream_t *	svn_stream_tee (svn_stream_t out1, svn_stream_t out2, apr_pool_t *pool)
	Return a writable stream which, when written to, writes to both of the underlying streams.
svn_error_t *	svn_stream_printf (svn_stream_t stream, apr_pool_t pool, const char *fmt,...)
	Write to stream using a printf-style fmt specifier, passed through apr_psprintf() using memory from pool.
svn_error_t *	svn_stream_printf_from_utf8 (svn_stream_t stream, const char encoding, apr_pool_t pool, const char fmt,...)
	Write to stream using a printf-style fmt specifier, passed through apr_psprintf() using memory from pool.
svn_error_t *	svn_stream_readline (svn_stream_t stream, svn_stringbuf_t stringbuf, const char eol, svn_boolean_t eof, apr_pool_t pool)
	Allocate stringbuf in pool, and read into it one line (terminated by eol) from stream*.
svn_error_t *	svn_stream_copy3 (svn_stream_t from, svn_stream_t to, svn_cancel_func_t cancel_func, void cancel_baton, apr_pool_t pool)
	Read the contents of the readable stream from and write them to the writable stream to calling cancel_func before copying each chunk.
svn_error_t *	svn_stream_copy2 (svn_stream_t from, svn_stream_t to, svn_cancel_func_t cancel_func, void cancel_baton, apr_pool_t pool)
	Same as svn_stream_copy3() but the streams are not closed.
svn_error_t *	svn_stream_copy (svn_stream_t from, svn_stream_t to, apr_pool_t *pool)
	Same as svn_stream_copy3(), but without the cancellation function or stream closing.
svn_error_t *	svn_stream_contents_same2 (svn_boolean_t same, svn_stream_t stream1, svn_stream_t stream2, apr_pool_t pool)
	Set same to TRUE if stream1* and stream2 have the same contents, else set it to FALSE.
svn_error_t *	svn_stream_contents_same (svn_boolean_t same, svn_stream_t stream1, svn_stream_t stream2, apr_pool_t pool)
	Same as svn_stream_contents_same2(), but the streams will not be closed.
svn_error_t *	svn_string_from_stream (svn_string_t *result, svn_stream_t stream, apr_pool_t result_pool, apr_pool_t scratch_pool)
	Read the contents of stream into memory, returning the data in result.

Detailed Description

Generic byte-streams.

Typedef Documentation

typedef svn_error_t*(* svn_close_fn_t)(void *baton)

Close handler function for a generic stream.

See also:: svn_stream_t.

Definition at line 765 of file svn_io.h.

typedef svn_error_t*(* svn_read_fn_t)(void *baton, char *buffer, apr_size_t *len)

Read handler function for a generic stream.

See also:: svn_stream_t.

Definition at line 748 of file svn_io.h.

typedef svn_error_t*(* svn_stream_mark_fn_t)(void *baton, svn_stream_mark_t **mark, apr_pool_t *pool)

Mark handler function for a generic stream.

See also:: svn_stream_t and svn_stream_mark().

Since:: New in 1.7.

Definition at line 781 of file svn_io.h.

typedef struct svn_stream_mark_t svn_stream_mark_t

An opaque type which represents a mark on a stream.

There is no concrete definition of this type, it is a named type for stream implementation specific baton pointers.

See also:: svn_stream_mark().

Since:: New in 1.7.

Definition at line 774 of file svn_io.h.

typedef svn_error_t*(* svn_stream_seek_fn_t)(void *baton, const svn_stream_mark_t *mark)

Seek handler function for a generic stream.

See also:: svn_stream_t and svn_stream_seek().

Since:: New in 1.7.

Definition at line 790 of file svn_io.h.

typedef svn_error_t*(* svn_stream_skip_fn_t)(void *baton, apr_size_t len)

Skip data handler function for a generic stream.

See also:: svn_stream_t and svn_stream_skip().

Since:: New in 1.7.

Definition at line 756 of file svn_io.h.

typedef struct svn_stream_t svn_stream_t

An abstract stream of bytes--either incoming or outgoing or both.

The creator of a stream sets functions to handle read and write. Both of these handlers accept a baton whose value is determined at stream creation time; this baton can point to a structure containing data associated with the stream. If a caller attempts to invoke a handler which has not been set, it will generate a runtime assertion failure. The creator can also set a handler for close requests so that it can flush buffered data or whatever; if a close handler is not specified, a close request on the stream will simply be ignored. Note that svn_stream_close() does not deallocate the memory used to allocate the stream structure; free the pool you created the stream in to free that memory.

The read and write handlers accept length arguments via pointer. 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.

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().

Definition at line 743 of file svn_io.h.

typedef svn_error_t*(* svn_write_fn_t)(void *baton, const char *data, apr_size_t *len)

Write handler function for a generic stream.

See also:: svn_stream_t.

Definition at line 760 of file svn_io.h.

Function Documentation

svn_stream_t* svn_stream_checksummed	(	svn_stream_t *	stream,
		const unsigned char **	read_digest,
		const unsigned char **	write_digest,
		svn_boolean_t	read_all,
		apr_pool_t *	pool
	)

Similar to svn_stream_checksummed2(), but always returning the MD5 checksum in read_digest and write_digest.

Since:: New in 1.4.

Deprecated:: Provided for backward compatibility with the 1.5 API.

svn_stream_t* svn_stream_checksummed2	(	svn_stream_t *	stream,
		svn_checksum_t **	read_checksum,
		svn_checksum_t **	write_checksum,
		svn_checksum_kind_t	checksum_kind,
		svn_boolean_t	read_all,
		apr_pool_t *	pool
	)

Return a stream that calculates checksums for all data read and written.

The stream stream is used to read and write all data. The stream and the resulting digests are allocated in pool.

When the stream is closed, *read_checksum and *write_checksum are set to point to the resulting checksums, of type read_checksum_kind and write_checksum_kind, respectively.

Both read_checksum and write_checksum can be NULL, in which case the respective checksum isn't calculated.

If read_all is TRUE, make sure that all data available on stream is read (and checksummed) when the stream is closed.

Read and write operations can be mixed without interfering.

The stream passed into this function is closed when the created stream is closed.

Since:: New in 1.6.

svn_error_t* svn_stream_close ( svn_stream_t * stream )

Close a generic stream.

See also:: svn_stream_t.

svn_stream_t* svn_stream_compressed	(	svn_stream_t *	stream,
		apr_pool_t *	pool
	)

Return a stream that decompresses all data read and compresses all data written.

The stream stream is used to read and write all compressed data. All compression data structures are allocated on pool. If compression support is not compiled in then svn_stream_compressed() returns stream unmodified. Make sure you call svn_stream_close() on the stream returned by this function, so that all data are flushed and cleaned up.

Note:: From 1.4, compression support is always compiled in.

svn_error_t* svn_stream_contents_same	(	svn_boolean_t *	same,
		svn_stream_t *	stream1,
		svn_stream_t *	stream2,
		apr_pool_t *	pool
	)

Same as svn_stream_contents_same2(), but the streams will not be closed.

Since:: New in 1.4.

Deprecated:: Provided for backward compatibility with the 1.6 API.

svn_error_t* svn_stream_contents_same2	(	svn_boolean_t *	same,
		svn_stream_t *	stream1,
		svn_stream_t *	stream2,
		apr_pool_t *	pool
	)

Set *same to TRUE if stream1 and stream2 have the same contents, else set it to FALSE.

Both streams will be closed before this function returns (regardless of the result, or any possible error).

Use scratch_pool for temporary allocations.

Since:: New in 1.7.

svn_error_t* svn_stream_copy	(	svn_stream_t *	from,
		svn_stream_t *	to,
		apr_pool_t *	pool
	)

Same as svn_stream_copy3(), but without the cancellation function or stream closing.

Since:: New in 1.1.

Deprecated:: Provided for backward compatibility with the 1.4 API.

svn_error_t* svn_stream_copy2	(	svn_stream_t *	from,
		svn_stream_t *	to,
		svn_cancel_func_t	cancel_func,
		void *	cancel_baton,
		apr_pool_t *	pool
	)

Same as svn_stream_copy3() but the streams are not closed.

Since:: New in 1.5.

Deprecated:: Provided for backward compatibility with the 1.5 API.

svn_error_t* svn_stream_copy3	(	svn_stream_t *	from,
		svn_stream_t *	to,
		svn_cancel_func_t	cancel_func,
		void *	cancel_baton,
		apr_pool_t *	pool
	)

Read the contents of the readable stream from and write them to the writable stream to calling cancel_func before copying each chunk.

cancel_func may be NULL.

Note:: both from and to will be closed upon successful completion of the copy (but an error may still be returned, based on trying to close the two streams). If the closure is not desired, then you can use svn_stream_disown() to protect either or both of the streams from being closed.

Since:: New in 1.6.

svn_stream_t* svn_stream_create	(	void *	baton,
		apr_pool_t *	pool
	)

Create a generic stream.

See also:: svn_stream_t.

svn_stream_t* svn_stream_disown	(	svn_stream_t *	stream,
		apr_pool_t *	pool
	)

Return a stream allocated in pool which forwards all requests to stream.

Destruction is explicitly excluded from forwarding.

See also:: notes/destruction-of-stacked-resources

Since:: New in 1.4.

svn_stream_t* svn_stream_empty ( apr_pool_t * pool )

Create a stream that is empty for reading and infinite for writing.

svn_error_t* svn_stream_for_stderr	(	svn_stream_t **	err,
		apr_pool_t *	pool
	)

Set *err to a generic stream connected to stderr, allocated in pool.

The stream and its underlying APR handle will be closed when pool is cleared or destroyed.

Since:: New in 1.7.

svn_error_t* svn_stream_for_stdin	(	svn_stream_t **	in,
		apr_pool_t *	pool
	)

Set *in to a generic stream connected to stdin, allocated in pool.

The stream and its underlying APR handle will be closed when pool is cleared or destroyed.

Since:: New in 1.7.

svn_error_t* svn_stream_for_stdout	(	svn_stream_t **	out,
		apr_pool_t *	pool
	)

Set *out to a generic stream connected to stdout, allocated in pool.

The stream and its underlying APR handle will be closed when pool is cleared or destroyed.

svn_stream_t* svn_stream_from_aprfile	(	apr_file_t *	file,
		apr_pool_t *	pool
	)

Similar to svn_stream_from_aprfile2(), except that the file will always be disowned.

Note:: The stream returned is not considered to "own" the underlying file, meaning that svn_stream_close() on the stream will not close the file.

Deprecated:: Provided for backward compatibility with the 1.3 API.

svn_stream_t* svn_stream_from_aprfile2	(	apr_file_t *	file,
		svn_boolean_t	disown,
		apr_pool_t *	pool
	)

Create a stream from an APR file.

For convenience, if file is NULL, an empty stream created by svn_stream_empty() is returned.

This function should normally be called with disown set to FALSE, in which case closing the stream will also close the underlying file.

If disown is TRUE, the stream will disown the underlying file, meaning that svn_stream_close() will not close the file.

Since:: New in 1.4.

svn_stream_t* svn_stream_from_string	(	const svn_string_t *	str,
		apr_pool_t *	pool
	)

Return a generic read-only stream connected to string str.

Allocate the stream in pool.

svn_stream_t* svn_stream_from_stringbuf	(	svn_stringbuf_t *	str,
		apr_pool_t *	pool
	)

Return a generic stream connected to stringbuf str.

Allocate the stream in pool.

svn_error_t* svn_stream_mark	(	svn_stream_t *	stream,
		svn_stream_mark_t **	mark,
		apr_pool_t *	pool
	)

Set a mark at the current position of a generic stream, which can later be sought back to using svn_stream_seek().

The mark is allocated in pool.

This function returns the SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error if the stream doesn't implement seeking.

See also:: svn_stream_seek()

Since:: New in 1.7.

svn_error_t* svn_stream_open_readonly	(	svn_stream_t **	stream,
		const char *	path,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Create a stream to read the file at path.

It will be opened using the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the perms. If you'd like to use different values, then open the file yourself, and use the svn_stream_from_aprfile2() interface.

The stream will be returned in stream, and allocated from result_pool. Temporary allocations will be performed in scratch_pool.

Since:: New in 1.6

svn_error_t* svn_stream_open_unique	(	svn_stream_t **	stream,
		const char **	temp_path,
		const char *	dirpath,
		svn_io_file_del_t	delete_when,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Create a writable stream to a file in the directory dirpath.

The file will have an arbitrary and unique name, and the full path will be returned in temp_path. The stream will be returned in stream. Both will be allocated from result_pool.

If dirpath is NULL, use the path returned from svn_io_temp_dir(). (Note that when using the system-provided temp directory, it may not be possible to atomically rename the resulting file due to cross-device issues.)

The file will be deleted according to delete_when.

Temporary allocations will be performed in scratch_pool.

Since:: New in 1.6

See also:: svn_io_open_unique_file3()

svn_error_t* svn_stream_open_writable	(	svn_stream_t **	stream,
		const char *	path,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Create a stream to write a file at path.

The file will be *created* using the APR_BUFFERED and APR_BINARY flag, and APR_OS_DEFAULT for the perms. The file will be created "exclusively", so if it already exists, then an error will be thrown. If you'd like to use different values, or open an existing file, then open the file yourself, and use the svn_stream_from_aprfile2() interface.

The stream will be returned in stream, and allocated from result_pool. Temporary allocations will be performed in scratch_pool.

Since:: New in 1.6

svn_error_t* svn_stream_printf_from_utf8	(	svn_stream_t *	stream,
		const char *	encoding,
		apr_pool_t *	pool,
		const char *	fmt,
			...
	)

Write to stream using a printf-style fmt specifier, passed through apr_psprintf() using memory from pool.

The resulting string will be translated to encoding before it is sent to stream.

Note:: Use APR_LOCALE_CHARSET to translate to the encoding of the current locale.

Since:: New in 1.3.

svn_error_t* svn_stream_read	(	svn_stream_t *	stream,
		char *	buffer,
		apr_size_t *	len
	)

Read from a generic stream.

See also:: svn_stream_t.

svn_error_t* svn_stream_readline	(	svn_stream_t *	stream,
		svn_stringbuf_t **	stringbuf,
		const char *	eol,
		svn_boolean_t *	eof,
		apr_pool_t *	pool
	)

Allocate *stringbuf in pool, and read into it one line (terminated by eol) from stream.

The line-terminator is read from the stream, but is not added to the end of the stringbuf. Instead, the stringbuf ends with a usual '\0'.

If stream runs out of bytes before encountering a line-terminator, then set *eof to TRUE, otherwise set *eof to FALSE.

svn_error_t* svn_stream_reset ( svn_stream_t * stream )

Reset a generic stream back to its origin.

E.g. On a file this would be implemented as a seek to position 0). This function returns a #SVN_ERR_STREAM_RESET_NOT_SUPPORTED error when the stream doesn't implement resetting.

Since:: New in 1.7.

svn_error_t* svn_stream_seek	(	svn_stream_t *	stream,
		const svn_stream_mark_t *	mark
	)

Seek to a mark in a generic stream.

This function returns the SVN_ERR_STREAM_SEEK_NOT_SUPPORTED error if the stream doesn't implement seeking. Passing NULL as mark, seeks to the start of the stream.

See also:: svn_stream_mark()

Since:: New in 1.7.

void svn_stream_set_mark	(	svn_stream_t *	stream,
		svn_stream_mark_fn_t	mark_fn
	)

Set stream's mark function to mark_fn.

Since:: New in 1.7.

void svn_stream_set_seek	(	svn_stream_t *	stream,
		svn_stream_seek_fn_t	seek_fn
	)

Set stream's seek function to seek_fn.

Since:: New in 1.7.

void svn_stream_set_skip	(	svn_stream_t *	stream,
		svn_stream_skip_fn_t	skip_fn
	)

Set stream's skip function to skip_fn.

Since:: New in 1.7

svn_error_t* svn_stream_skip	(	svn_stream_t *	stream,
		apr_size_t	len
	)

Skip len bytes from a generic stream.

If the stream is exhausted before len bytes have been read, return an error.

Note:: No assumption can be made on the semantics of this function other than that the stream read pointer will be advanced by *len bytes. Depending on the capabilities of the underlying stream implementation, this may for instance be translated into a sequence of reads or a simple seek operation. If the stream implementation has not provided a skip function, this will read from the stream and discard the data.

svn_boolean_t svn_stream_supports_mark ( svn_stream_t * stream )

Returns TRUE if the generic stream supports svn_stream_mark().

See also:: svn_stream_mark()

Since:: New in 1.7.

svn_stream_t* svn_stream_tee	(	svn_stream_t *	out1,
		svn_stream_t *	out2,
		apr_pool_t *	pool
	)

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 behavior. One or both of out1 and out2 may be NULL. If both are NULL, NULL is returned.

Since:: New in 1.7.

svn_error_t* svn_stream_write	(	svn_stream_t *	stream,
		const char *	data,
		apr_size_t *	len
	)

Write to a generic stream.

See also:: svn_stream_t.

svn_error_t* svn_string_from_stream	(	svn_string_t **	result,
		svn_stream_t *	stream,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Read the contents of stream into memory, returning the data in result.

The stream will be closed when it has been successfully and completely read.

The returned memory is allocated in result_pool, and any temporary allocations are performed in scratch_pool.

Note:: due to memory pseudo-reallocation behavior (due to pools), this can be a memory-intensive operation for large files.

Since:: New in 1.6

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation