fdbuf.h File Reference

Buffering subsystem used to guarantee completeness of read buffers using non-blocking interfaces. More...

Go to the source code of this file.

Classes
struct	FDBuf
Defines
#define	FDBUF_ERR   (-1) /**< Low-level error, examine errno */
#define	FDBUF_AGAIN   (-2) /**< Convenience for EAGAIN */
#define	FDBUF_EOF   (-3) /**< End-Of-File or remote termination */
#define	FDBUF_NVAL   (-4) /**< Invalid argument */
#define	fdbuf_delim   fdbuf_delim_string
Typedefs
typedef int(*	FDBufRead )(int fd, void *buf, size_t len, void *udata)
Functions
EXTERN_C_BEGIN LIBGIFT_EXPORT FDBuf *	fdbuf_new (int fd, FDBufRead readfn, FDBufRead peekfn, void *udata)
LIBGIFT_EXPORT void	fdbuf_free (FDBuf *buf)
LIBGIFT_EXPORT int	fdbuf_fill (FDBuf *buf, int bufsize)
LIBGIFT_EXPORT int	fdbuf_delim_string (FDBuf *buf, const char *delim)
LIBGIFT_EXPORT int	fdbuf_delim_set (FDBuf *buf, const char *delim_set)
LIBGIFT_EXPORT int	fdbuf_delim_char (FDBuf *buf, char delim)
LIBGIFT_EXPORT unsigned char *	fdbuf_data (FDBuf *buf, size_t *len)
LIBGIFT_EXPORT void	fdbuf_release (FDBuf *buf)

---

Detailed Description

Buffering subsystem used to guarantee completeness of read buffers using non-blocking interfaces.

This interface is intended to be used through a TCPC object. A buffer will be created on ::tcp_open or ::tcp_accept.

---

Define Documentation

#define FDBUF_AGAIN   (-2) /**< Convenience for EAGAIN */

Convenience for EAGAIN

#define FDBUF_EOF   (-3) /**< End-Of-File or remote termination */

End-Of-File or remote termination

#define FDBUF_ERR   (-1) /**< Low-level error, examine errno */

Low-level error, examine errno

#define FDBUF_NVAL   (-4) /**< Invalid argument */

Invalid argument

---

Typedef Documentation

typedef int(* FDBufRead)(int fd, void *buf, size_t len, void *udata)

Prototype for the buffer read function. Parameters: fd  buf  len  udata  Returns: Number of bytes successfully read. Returns 0 on end-of-file and -1 on error, and errno will be examined by the caller.

---

Function Documentation

LIBGIFT_EXPORT unsigned char* fdbuf_data (  FDBuf *  buf, size_t *  len )

Accessor for the data segment filled into the buffer. Parameters: buf  len  Storage location to "return" the length of the data buffer. If NULL, no action will be taken on this parameter.

LIBGIFT_EXPORT int fdbuf_delim_char (  FDBuf *  buf, char  delim )

Similar to ::fdbuf_delim, but uses a single character as the delimiter.

LIBGIFT_EXPORT int fdbuf_delim_set (  FDBuf *  buf, const char *  delim_set )

Similar to fdbuf_delim_char, but takes a set of single-char delimiters.

LIBGIFT_EXPORT int fdbuf_delim_string (  FDBuf *  buf, const char *  delim )

Search for the specific delim string on the input buffers. This currently requires "peek" functionality on the file descriptor, and as such will only work on sockets. This is a bug and should be fixed. Parameters: buf  delim  NUL-terminated delim string. This is not a set of delims. Returns: Number of bytes read without locating the delim string or 0 if delim was found. Negative return values have the same result as in fdbuf_fill.

LIBGIFT_EXPORT int fdbuf_fill (  FDBuf *  buf, int  bufsize )

Fill the internal buffer up to bufsize. Parameters: buf  bufsize  Total number of bytes requested to be filled. Returns: Number of bytes remaining to fill bufsize. A return value of 0 indicates that bufsize is completely satisfied. A negative value indicates an internal error condition and you may check with the return codes described above. The appropriate errno function may be used to query the low-level error.

LIBGIFT_EXPORT void fdbuf_free (  FDBuf *  buf  )

Destroy a buffer instance.

EXTERN_C_BEGIN LIBGIFT_EXPORT FDBuf* fdbuf_new (  int  fd, FDBufRead  readfn, FDBufRead  peekfn, void *  udata )

Construct a new buffer instance. This should only be done once per file descriptor, as the object instance must persist in order to take advantage of the buffering. Parameters: fd  File descriptor to read. readfn  Optional interface for reading data. If NULL, socket recv peekfn  Optional interface for peeking data. If NULL, MSG_PEEK will be used. udata  Arbitrary data passed along to readfn, peekfn, and attached to the FDBuf object.

LIBGIFT_EXPORT void fdbuf_release (  FDBuf *  buf  )

Flush the currently populated buffer to begin anew. This does not invalidate the calling argument, merely the data buffers held within.

---