2
Copyright (C) 2008- The University of Notre Dame
3
This software is distributed under the GNU General Public License.
4
See the file COPYING for details.
13
/** @file chirp_stream.h
14
Streaming I/O interface.
15
This module implements <i>streaming I/O</i> against a Chirp server.
16
In this model, the user can read and write small amounts of data
17
in a continuous stream to or from a remote file.
18
This interface gives higher data throughput than the @ref chirp_reli.h
19
interface, but it is <i>unreliable</i>. If a streaming connection is
20
lost, the client must close it and start all over again. If reliability
21
is more important than performance, use the @ref chirp_reli.h interface instead.
24
/** Indicates what mode to be used for opening a stream.*/
26
CHIRP_STREAM_READ, /**< Open the stream for reading. */
27
CHIRP_STREAM_WRITE, /**< Open the stream for writing. */
28
} chirp_stream_mode_t;
30
/** Open a new stream for reading or writing.
31
Connects to a named server and creates a stream for reading or writing to the given file.
32
@param hostport The host and optional port number of the Chirp server.
33
@param path The pathname of the file to access.
34
@param mode The mode of the stream, either @ref CHIRP_STREAM_READ or @ref CHIRP_STREAM_WRITE.
35
@param stoptime The absolute time at which to abort.
36
@return On success, returns a handle to a chirp_stream. On failure, returns zero and sets errno appropriately.
39
struct chirp_stream * chirp_stream_open( const char *hostport, const char *path, chirp_stream_mode_t mode, time_t stoptime );
41
/** Print formatted data to a stream with buffering.
42
Writes formatted data to a stream, just like a standard Unix printf.
43
@param stream A stream created by @ref chirp_stream_open.
44
@param stoptime The absolute time at which to abort.
45
@param fmt A printf-style format string, followed by the data to transmit.
46
@return On success, returns the number of characters written to the stream. On failure, returns less than zero and sets errno appropriately.
49
int chirp_stream_printf( struct chirp_stream *stream, time_t stoptime, const char *fmt, ... );
51
/** Read a single line from a stream with buffering.
52
Reads a single line terminated by a linefeed (ASCII byte 10). Carriage returns (ASCII byte 13) are ignored and removed from the input.
53
@param stream A stream created by @ref chirp_stream_open.
54
@param line A pointer to a buffer where the line can be placed.
55
@param length The size of the buffer in bytes.
56
@param stoptime The absolute time at which to abort.
57
@return On success, the number of bytes actually read. On end-of-stream, returns zero. On failure, returns less than zero and sets errno appropriately.
59
int chirp_stream_readline( struct chirp_stream *stream, char *line, int length, time_t stoptime );
61
/** Write data to a stream.
62
@param stream A stream created by @ref chirp_stream_open.
63
@param data A pointer to a buffer of data to write.
64
@param length The size of the buffer in bytes.
65
@param stoptime The absolute time at which to abort.
66
@return On success, the number of bytes actually written. On failure, returns less than zero and sets errno appropriately.
69
int chirp_stream_write( struct chirp_stream *stream, const void *data, int length, time_t stoptime );
71
/** Read data from a stream.
72
@param stream A stream created by @ref chirp_stream_open.
73
@param data A pointer to a buffer where data can be placed.
74
@param length The size of the buffer in bytes.
75
@param stoptime The absolute time at which to abort.
76
@return On success, the number of bytes actually read. On end-of-stream, returns zero. On failure, returns less than zero and sets errno appropriately.
79
int chirp_stream_read( struct chirp_stream *stream, void *data, int length, time_t stoptime );
81
/** Flush buffered data to the stream.
82
@param stream A stream created by @ref chirp_stream_open.
83
@param stoptime The absolute time at which to abort.
84
@return On success, returns the number of characters written to the stream. On failure, returns less than zero and sets errno appropriately.
87
int chirp_stream_flush( struct chirp_stream *stream, time_t stoptime );
90
This routine closes and deallocates all state associated with a stream.
91
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.
92
@param stream A stream created by @ref chirp_stream_open.
93
@param stoptime The absolute time at which to abort.
94
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno appropriately.
97
int chirp_stream_close( struct chirp_stream *stream, time_t stoptime );
added
removed
chirp/src/chirp_stream.h
