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

## chirp_stream_mode_t

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

## chirp_stream_open()

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.

## chirp_stream_printf()

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.

## chirp_stream_readline()

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.

## chirp_stream_write()

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.

## chirp_stream_read()

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.

## chirp_stream_flush()

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.

## chirp_stream_close()

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.