chirp_stream.h File Reference

Streaming I/O interface. More...

#include <sys/time.h>
#include <stdio.h>

Go to the source code of this file.

Enumerations
enum	chirp_stream_mode_t {   CHIRP_STREAM_READ,   CHIRP_STREAM_WRITE }
	Indicates what mode to be used for opening a stream. More...

Functions
struct chirp_stream *	chirp_stream_open (const char *hostport, const char *path, chirp_stream_mode_t mode, time_t stoptime)
	Open a new stream for reading or writing. More...
int	chirp_stream_printf (struct chirp_stream *stream, time_t stoptime, const char *fmt,...)
	Print formatted data to a stream with buffering. More...
int	chirp_stream_readline (struct chirp_stream *stream, char *line, int length, time_t stoptime)
	Read a single line from a stream with buffering. More...
int	chirp_stream_write (struct chirp_stream *stream, const void *data, int length, time_t stoptime)
	Write data to a stream. More...
int	chirp_stream_read (struct chirp_stream *stream, void *data, int length, time_t stoptime)
	Read data from a stream. More...
int	chirp_stream_flush (struct chirp_stream *stream, time_t stoptime)
	Flush buffered data to the stream. More...
int	chirp_stream_close (struct chirp_stream *stream, time_t stoptime)
	Closes a stream. More...

Detailed Description

Streaming I/O interface.

This module implements streaming I/O against a Chirp server. In this model, the user can read and write small amounts of data in a continuous stream to or from a remote file. This interface gives higher data throughput than the chirp_reli.h interface, but it is unreliable. If a streaming connection is lost, the client must close it and start all over again. If reliability is more important than performance, use the chirp_reli.h interface instead.

Enumeration Type Documentation

enum chirp_stream_mode_t

Indicates what mode to be used for opening a stream.

Enumerator
CHIRP_STREAM_READ	Open the stream for reading.
CHIRP_STREAM_WRITE	Open the stream for writing.

Function Documentation

struct chirp_stream* chirp_stream_open	(	const char *	hostport,
		const char *	path,
		chirp_stream_mode_t	mode,
		time_t	stoptime
	)

Open a new stream for reading or writing.

Connects to a named server and creates a stream for reading or writing to the given file.

Parameters

hostport	The host and optional port number of the Chirp server.
path	The pathname of the file to access.
mode	The mode of the stream, either CHIRP_STREAM_READ or CHIRP_STREAM_WRITE.
stoptime	The absolute time at which to abort.

Returns

On success, returns a handle to a chirp_stream. On failure, returns zero and sets errno appropriately.

int chirp_stream_printf	(	struct chirp_stream *	stream,
		time_t	stoptime,
		const char *	fmt,
			...
	)

Print formatted data to a stream with buffering.

Writes formatted data to a stream, just like a standard Unix printf.

Parameters

stream	A stream created by chirp_stream_open.
stoptime	The absolute time at which to abort.
fmt	A printf-style format string, followed by the data to transmit.

Returns

On success, returns the number of characters written to the stream. On failure, returns less than zero and sets errno appropriately.

int chirp_stream_readline	(	struct chirp_stream *	stream,
		char *	line,
		int	length,
		time_t	stoptime
	)

Read a single line from a stream with buffering.

Reads a single line terminated by a linefeed (ASCII byte 10). Carriage returns (ASCII byte 13) are ignored and removed from the input.

Parameters

stream	A stream created by chirp_stream_open.
line	A pointer to a buffer where the line can be placed.
length	The size of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns

On success, the number of bytes actually read. On end-of-stream, returns zero. On failure, returns less than zero and sets errno appropriately.

int chirp_stream_write	(	struct chirp_stream *	stream,
		const void *	data,
		int	length,
		time_t	stoptime
	)

Write data to a stream.

Parameters

stream	A stream created by chirp_stream_open.
data	A pointer to a buffer of data to write.
length	The size of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns

On success, the number of bytes actually written. On failure, returns less than zero and sets errno appropriately.

int chirp_stream_read	(	struct chirp_stream *	stream,
		void *	data,
		int	length,
		time_t	stoptime
	)

Read data from a stream.

Parameters

stream	A stream created by chirp_stream_open.
data	A pointer to a buffer where data can be placed.
length	The size of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns

On success, the number of bytes actually read. On end-of-stream, returns zero. On failure, returns less than zero and sets errno appropriately.

int chirp_stream_flush	(	struct chirp_stream *	stream,
		time_t	stoptime
	)

Flush buffered data to the stream.

Parameters

stream	A stream created by chirp_stream_open.
stoptime	The absolute time at which to abort.

Returns

On success, returns the number of characters written to the stream. On failure, returns less than zero and sets errno appropriately.

int chirp_stream_close	(	struct chirp_stream *	stream,
		time_t	stoptime
	)

Closes a stream.

This routine closes and deallocates all state associated with a stream. Note that a stream may buffer data internally, so the called does not know if all data has been written successfully unless this function returns success.

Parameters

stream	A stream created by chirp_stream_open.
stoptime	The absolute time at which to abort.

Returns

On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno appropriately.