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.
int chirp_stream_printf (struct chirp_stream *stream, time_t stoptime, const char *fmt,...)
 Print formatted data to a stream with buffering.
int chirp_stream_readline (struct chirp_stream *stream, char *line, int length, time_t stoptime)
 Read a single line from a stream with buffering.
int chirp_stream_write (struct chirp_stream *stream, const void *data, int length, time_t stoptime)
 Write data to a stream.
int chirp_stream_read (struct chirp_stream *stream, void *data, int length, time_t stoptime)
 Read data from a stream.
int chirp_stream_flush (struct chirp_stream *stream, time_t stoptime)
 Flush buffered data to the stream.
int chirp_stream_close (struct chirp_stream *stream, time_t stoptime)
 Closes a stream.

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 
)
read

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.