Basic IO Functions

Basic IO Functions — Functions for stacking various I/O layers on top of each other

Synopsis


#include <monitor/monitor.h>


            mon_bio_head;
enum        mon_bio_head_type;
enum        mon_bio_head_flags;
            mon_bio_ops;
enum        mon_bio_capabilities;
            mon_bio;
enum        mon_bio_flags;
enum        mon_bio_ctrl;
int         mon_bio_head_init               (mon_bio_head *bh,
                                             mon_bio_head_type type,
                                             size_t rbuf_size,
                                             size_t wbuf_size);
void        mon_bio_head_destroy            (mon_bio_head *bh);
int         mon_bio_head_add                (mon_bio_head *bh,
                                             mon_bio *bio);
int         mon_bio_head_close              (mon_bio_head *bh);
int         mon_bio_head_accept             (mon_bio_head *bh);
int         mon_bio_head_connect            (mon_bio_head *bh);
int         mon_bio_head_control            (mon_bio_head *bh,
                                             mon_bio_ctrl option,
                                             void *arg);
int         mon_bio_head_flush              (mon_bio_head *bh);
int         mon_bio_head_read               (mon_bio_head *bh,
                                             size_t maxlen);
int         mon_bio_head_write              (mon_bio_head *bh);
int         mon_bio_head_get_fd             (mon_bio_head *bh);
void        mon_bio_head_set_fd             (mon_bio_head *bh,
                                             int fd);
int         mon_bio_register                (const mon_bio_ops *ops);
void        mon_bio_unregister              (const mon_bio_ops *ops);
int         mon_bio_register_builtin        (void);
void        mon_bio_unregister_builtin      (void);
int         mon_bio_check_config            (mon_cfg_node *root,
                                             const char *filename);
int         mon_bio_list_registered         (mon_arg_list *list,
                                             const char *argname,
                                             mon_bio_capabilities caps);
mon_bio*    mon_bio_new                     (const mon_bio_ops *ops,
                                             void *priv);
void        mon_bio_free                    (mon_bio *bio);
int         mon_bio_create                  (const char *name,
                                             mon_bio_head_type type,
                                             mon_cfg_node *root,
                                             mon_auth_state *auth,
                                             mon_bio **bio);
int         mon_bio_read                    (mon_bio *bio,
                                             mon_buffer *dst,
                                             size_t maxlen);
int         mon_bio_write                   (mon_bio *bio,
                                             mon_buffer *src);
int         mon_bio_flush                   (mon_bio *bio);
mon_bio*    mon_bio_next                    (mon_bio *bio);

#define     MON_BIO_USERSHIFT

Description

Details

mon_bio_head

typedef struct {
	mon_bio_head_type	type;
	mon_bio_head_flags	flags;
	GList			*bios;

	int			fd;

	/* Input and output buffers */
	mon_buffer		rbuf;
	mon_buffer		wbuf;
	size_t			rbuf_max;
	size_t			wbuf_max;

	/* Used by connect & accept */
	GList			*curr_bio;
} mon_bio_head;

The mon_bio_head structure is the main descriptor for using the basic I/O abstraction layer. It contains and coordinates mon_bio layers.

mon_bio_head_type `type`;	the type of the BIO head.
mon_bio_head_flags `flags`;	flags for the whole BIO stack.
GList *`bios`;	the list of BIOs in use.
int `fd`;	the file descriptor for the lowest level BIO.
mon_buffer `rbuf`;	the read buffer.
mon_buffer `wbuf`;	the write buffer.
size_t `rbuf_max`;	maximum allowed size of the read buffer.
size_t `wbuf_max`;	maximum allowed size of the write buffer.
GList *`curr_bio`;	the current BIO for some operations.

enum mon_bio_head_type

typedef enum {
	MON_BH_ACCEPT,
	MON_BH_CONNECT
} mon_bio_head_type;

The type of the BIO head.

`MON_BH_ACCEPT`	server-side
`MON_BH_CONNECT`	client-side

enum mon_bio_head_flags

typedef enum {
	MON_BH_READAHEAD	= (1 << 0),
	MON_BH_WANT_READ	= (1 << 1),
	MON_BH_WANT_WRITE	= (1 << 2)
} mon_bio_head_flags;

Flags for the whole BIO stack.

`MON_BH_READAHEAD`	Read-ahead is enabled.
`MON_BH_WANT_READ`	The last operation should be retried when more data is available on the source BIO.
`MON_BH_WANT_WRITE`	The last operation should be retried when the sink BIO is able to write out data.

mon_bio_ops

typedef struct {
	char			*name;
	mon_bio_capabilities	caps;
	const mon_cfg_desc	*params;

	/* Allocate internal resources for the bio */
	int			(*setup)(mon_bio *bio, mon_bio_head_type type,
					mon_cfg_node *cfg,
					mon_auth_state *auth);
	/* Destroy the bio */
	void			(*done)(mon_bio *bio);

	/* Read some data */
	int			(*read)(mon_bio *bio, mon_buffer *dst,
					size_t maxlen);
	/* Write some data */
	int			(*write)(mon_bio *bio, mon_buffer *src);
	/* Flush data in output buffers */
	int			(*flush)(mon_bio *bio);
	/* Perform bio-specific operations */
	int			(*control)(mon_bio *bio, mon_bio_ctrl option,
					void *arg);
	/* Do the client-side handshaking when setting up the bio */
	int			(*connect)(mon_bio *bio);
	/* Do the server-side handshaking when setting up the bio */
	int			(*accept)(mon_bio *bio);
	/* Reset the underlying medium (close the connection), but keep
	 * the bio alive */
	int			(*close)(mon_bio *bio);
} mon_bio_ops;

The mon_bio_ops structure defines the operations that can be performed on a mon_bio.

char *`name`;	the name of the bio (for debugging)
mon_bio_capabilities `caps`;	one or more of `mon_bio_capabilities`.
const mon_cfg_desc *`params`;	array of mon_cfg_desc descriptors describing the possible configuration parameters for this BIO.
`setup` ()	set up the internal state of a mon_bio.
`done` ()	close and release a mon_bio.
`read` ()	read data from a mon_bio.
`write` ()	write data to a mon_bio.
`flush` ()	flush all data that is still stored in internal buffers.
`control` ()	used to manipulate a mon_bio.
`connect` ()	perform the client-side handshaking when setting up a mon_bio.
`accept` ()	perform the server-side handshaking when setting up a mon_bio.
`close` ()	close a mon_bio but do not release it (so reconnecting is possible).

enum mon_bio_capabilities

typedef enum {
	MON_BIO_CAP_FILTER	= (1 << 0),
	/* Provides link-level authentication */
	MON_BIO_CAP_LINKAUTH	= (1 << 1),
	/* Requires authentication before the BIO can be used */
	MON_BIO_CAP_NEEDAUTH	= (1 << 2)
} mon_bio_capabilities;

Flags describing BIO capabilities.

`MON_BIO_CAP_FILTER`	the BIO is a filter.
`MON_BIO_CAP_LINKAUTH`	the BIO provides transport level authentication.
`MON_BIO_CAP_NEEDAUTH`	the BIO can only be used after a successful authentication using the same authentication method as the BIO name.

mon_bio

typedef struct {
	/* Bits 0-15 are for general use, bits 16-31 are bio-private */
	mon_bio_flags		flags;
	int			level;
	const mon_bio_ops	*ops;
	void			*priv;


	/* Pointer to the mon_bio_head this bio belongs to */
	mon_bio_head		*head;

	/* Pointer to the appropriate list element in head->bios */
	GList			*link;
} mon_bio;

The mon_bio structure represents a basic I/O abstraction layer.

mon_bio_flags `flags`;	BIO flags.
int `level`;	the level which the BIO should be installed at.
const mon_bio_ops *`ops`;	BIO operations.
void *`priv`;	BIO-private data.
mon_bio_head *`head`;	the mon_bio_head this BIO belongs to.
GList *`link`;	used to implement `mon_bio_next()`.

enum mon_bio_flags

typedef enum {
	MON_BIO_SINGLESHOT	= (1 << 0),
	MON_BIO_AUTOFLUSH	= (1 << 1),
	MON_BIO_CONNECTED	= (1 << 2),
	MON_BIO_ACCEPTED	= (1 << 3),
	MON_BIO_DO_CONNECT	= (1 << 4),
	MON_BIO_DO_ACCEPT	= (1 << 5),
	MON_BIO_WANT_READ	= (1 << 6),
	MON_BIO_WANT_WRITE	= (1 << 7)
} mon_bio_flags;

BIO flags.

`MON_BIO_SINGLESHOT`	if this flag is set for a BIO, the BIO will only do at most one physical read operations. When a second read operation would be neccessary, the error code `MON_WANT_READ` will be returned instead. After getting `MON_WANT_READ`, the indicator should be reset using the `MON_BIO_CTL_SINGLESHOT_RESET` control.
`MON_BIO_AUTOFLUSH`	This flag tells that the BIO should do a flush (or equivalent) after every write operation.
`MON_BIO_CONNECTED`	if set, the `connect()` method of the mon_bio has been completed.
`MON_BIO_ACCEPTED`	if set, the `accept()` method of the mon_bio had been completed.
`MON_BIO_DO_CONNECT`	if set, the `connect()` method of the mon_bio should be called before a `read()` or `write()` operation.
`MON_BIO_DO_ACCEPT`	if set, the `accept()` method of the mon_bio should be called before a `read()` or `write()` operation.
`MON_BIO_WANT_READ`	if set, the BIO must read more data from the lower levels before it can continue
`MON_BIO_WANT_WRITE`	if set, the BIO must send data to the lower levels before it can continue

enum mon_bio_ctrl

typedef enum {
	MON_BIO_CTL_SET_READAHEAD,
	MON_BIO_CTL_GET_READAHEAD,
	MON_BIO_CTL_SINGLESHOT_RESET,
	MON_BIO_CTL_CHECK_AUTHSTATE,
	MON_BIO_CTL_SETUP_AUTHSTATE
} mon_bio_ctrl;

Operation codes used for manipulating mon_bio_head structures.

`MON_BIO_CTL_SET_READAHEAD`	set the readahead flag to the value of the control's argument (which must be an int *)
`MON_BIO_CTL_GET_READAHEAD`	retrieve the value of the read-ahead flag.
`MON_BIO_CTL_SINGLESHOT_RESET`	reset the singleshot indicator so the next read operation may invoke a physical read again
`MON_BIO_CTL_CHECK_AUTHSTATE`	check if there is a mon_bio installed that supports transport level authentication.
`MON_BIO_CTL_SETUP_AUTHSTATE`	prepare a mon_auth_state for transport level authentication. The argument of this control is a pointer to the mon_auth_state.

mon_bio_head_init ()

int         mon_bio_head_init               (mon_bio_head *bh,
                                             mon_bio_head_type type,
                                             size_t rbuf_size,
                                             size_t wbuf_size);

Initialize a mon_bio_head.

`bh` :	a mon_bio_head.
`type` :	the type of the BIO head (`MON_BH_ACCEPT` or `MON_BH_CONNECT`).
`rbuf_size` :	the size of the read buffer.
`wbuf_size` :	the size of the write buffer.
Returns :	0 if successful or an error code.

mon_bio_head_destroy ()

void        mon_bio_head_destroy            (mon_bio_head *bh);

Destroys a mon_bio_head and releases all allocated resources.

bh : a mon_bio_head.

mon_bio_head_add ()

int         mon_bio_head_add                (mon_bio_head *bh,
                                             mon_bio *bio);

Add a mon_bio layer to a mon_bio_head.

`bh` :	a mon_bio_head.
`bio` :	a mon_bio.
Returns :	0 if successful or an error code.

mon_bio_head_close ()

int         mon_bio_head_close              (mon_bio_head *bh);

Close all mon_bio layers of a mon_bio_head structure but keep them allocated. This way the underlying connection can be re-opened.

`bh` :	a mon_bio_head.
Returns :	0 if successful or an error code.

mon_bio_head_accept ()

int         mon_bio_head_accept             (mon_bio_head *bh);

Perform the server-side handshaking for all layers in a mon_bio_head.

`bh` :	a mon_bio_head.
Returns :	0 if successful or an error code.

mon_bio_head_connect ()

int         mon_bio_head_connect            (mon_bio_head *bh);

Perform the client-side handshaking for all layers in a mon_bio_head.

`bh` :	a mon_bio_head.
Returns :	0 if successful or an error code.

mon_bio_head_control ()

int         mon_bio_head_control            (mon_bio_head *bh,
                                             mon_bio_ctrl option,
                                             void *arg);

Manipulate the I/O layers in a mon_bio_head.

`bh` :	a mon_bio_head.
`option` :	the operation to perform. Can be one of the mon_bio_ctrl codes.
`arg` :	the argument of the operation. The actual data type depends on the operation.
Returns :	0 if successful or an error code.

mon_bio_head_flush ()

int         mon_bio_head_flush              (mon_bio_head *bh);

Flush any buffered writes.

`bh` :	a mon_bio_head.
Returns :	0 if successful (there is no data left in temporary buffers), `MON_WANT_WRITE` if the function has to be called again when the underlying media can accept more data, or an error code.

mon_bio_head_read ()

int         mon_bio_head_read               (mon_bio_head *bh,
                                             size_t maxlen);

Read data to the read buffer of a mon_bio_head. This function calls the read method of the top-level mon_bio.

`bh` :	a mon_bio_head.
`maxlen` :	the amount of data to read. If readahead is enabled, this value is ignored.
Returns :	0 if successful or an error code.

mon_bio_head_write ()

int         mon_bio_head_write              (mon_bio_head *bh);

Write data from the write buffer of a mon_bio_head. This function calls the write method of the top-level mon_bio.

`bh` :	a mon_bio_head.
Returns :	0 if successful or an error code.

mon_bio_head_get_fd ()

int         mon_bio_head_get_fd             (mon_bio_head *bh);

Returns the file descriptor used by the BIO stack.

`bh` :	a mon_bio_head.
Returns :	the file descriptor.

mon_bio_head_set_fd ()

void        mon_bio_head_set_fd             (mon_bio_head *bh,
                                             int fd);

Sets the file descriptor to be used by the BIO stack.

`bh` :	a mon_bio_head.
`fd` :	the file descriptor to use.

mon_bio_register ()

int         mon_bio_register                (const mon_bio_ops *ops);

Registers a mon_bio_ops structure.

`ops` :	a mon_bio_ops.
Returns :	0 if successful or an error code.

mon_bio_unregister ()

void        mon_bio_unregister              (const mon_bio_ops *ops);

Unregisters a mon_bio_ops structure.

ops : a mon_bio_ops.

mon_bio_register_builtin ()

int         mon_bio_register_builtin        (void);

Registers all built-in BIOs.

Returns :

0 if successful or an error code.

mon_bio_unregister_builtin ()

void        mon_bio_unregister_builtin      (void);

Unregisters all built-in BIOs. Must be called the same times as mon_bio_register_builtin() was called.

mon_bio_check_config ()

int         mon_bio_check_config            (mon_cfg_node *root,
                                             const char *filename);

Checks the BIO configurations

`root` :	root of a configuration tree containing the BIO configurations.
`filename` :	name of the configuration file to use in log messages.
Returns :	0 if successful or an error code.

mon_bio_list_registered ()

int         mon_bio_list_registered         (mon_arg_list *list,
                                             const char *argname,
                                             mon_bio_capabilities caps);

Adds the name of all registered BIOs to list with the key argname.

`list` :	a mon_arg_list.
`argname` :	the key name to use for adding the BIO names.
`caps` :	required capability flags. Only BIOs having all the requested capabilities will be listed.
Returns :	0 if successful or an error code.

mon_bio_new ()

mon_bio*    mon_bio_new                     (const mon_bio_ops *ops,
                                             void *priv);

Allocate a new mon_bio structure.

`ops` :	the operation descriptor for the mon_bio.
`priv` :	an opaque private data pointer.
Returns :	a mon_bio or `NULL` if there were not enough memory.

mon_bio_free ()

void        mon_bio_free                    (mon_bio *bio);

Free a mon_bio structure.

bio : a mon_bio.

mon_bio_create ()

int         mon_bio_create                  (const char *name,
                                             mon_bio_head_type type,
                                             mon_cfg_node *root,
                                             mon_auth_state *auth,
                                             mon_bio **bio);

Creates and initializes mon_bio.

`name` :	the name of the BIO.
`type` :	either `MON_BIO_ACCEPT` or `MON_BIO_CONNECT`.
`root` :	the root of the configuration tree containing the BIO configurations.
`auth` :	a mon_auth_state. This is required if the BIO has the `MON_BIO_CAP_NEEDAUTH` capability set.
`bio` :	pointer to store the new mon_bio if successful.
Returns :	0 if successful or an error code.

mon_bio_read ()

int         mon_bio_read                    (mon_bio *bio,
                                             mon_buffer *dst,
                                             size_t maxlen);

Read data from a mon_bio.

`bio` :	a mon_bio.
`dst` :	the destination mon_buffer.
`maxlen` :	the amount of data to read.
Returns :	0 if successful or an error code.

mon_bio_write ()

int         mon_bio_write                   (mon_bio *bio,
                                             mon_buffer *src);

Write data to a mon_bio.

`bio` :	a mon_bio.
`src` :	the source mon_buffer.
Returns :	0 if successful or an error code.

mon_bio_flush ()

int         mon_bio_flush                   (mon_bio *bio);

Flush any buffered data.

`bio` :	a mon_bio.
Returns :	0 if successful or an error code.

mon_bio_next ()

mon_bio*    mon_bio_next                    (mon_bio *bio);

The next lower-level bio from the mon_bio_head structure containing this mon_bio.

`bio` :	a mon_bio.
Returns :	the next lower-level mon_bio.

MON_BIO_USERSHIFT

#define	MON_BIO_USERSHIFT	16

This macro contains the shift value where BIO-private flag values may start.