cctools
Enumerations | Functions
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

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
hostportThe host and optional port number of the Chirp server.
pathThe pathname of the file to access.
modeThe mode of the stream, either CHIRP_STREAM_READ or CHIRP_STREAM_WRITE.
stoptimeThe 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
streamA stream created by chirp_stream_open.
stoptimeThe absolute time at which to abort.
fmtA 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
streamA stream created by chirp_stream_open.
lineA pointer to a buffer where the line can be placed.
lengthThe size of the buffer in bytes.
stoptimeThe 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
streamA stream created by chirp_stream_open.
dataA pointer to a buffer of data to write.
lengthThe size of the buffer in bytes.
stoptimeThe 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
streamA stream created by chirp_stream_open.
dataA pointer to a buffer where data can be placed.
lengthThe size of the buffer in bytes.
stoptimeThe 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
streamA stream created by chirp_stream_open.
stoptimeThe 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
streamA stream created by chirp_stream_open.
stoptimeThe 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.