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_ACCEPTserver-side
MON_BH_CONNECTclient-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_READAHEADRead-ahead is enabled.
MON_BH_WANT_READThe last operation should be retried when more data is available on the source BIO.
MON_BH_WANT_WRITEThe 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_FILTERthe BIO is a filter.
MON_BIO_CAP_LINKAUTHthe BIO provides transport level authentication.
MON_BIO_CAP_NEEDAUTHthe 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_SINGLESHOTif 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_AUTOFLUSHThis flag tells that the BIO should do a flush (or equivalent) after every write operation.
MON_BIO_CONNECTEDif set, the connect() method of the mon_bio has been completed.
MON_BIO_ACCEPTEDif set, the accept() method of the mon_bio had been completed.
MON_BIO_DO_CONNECTif set, the connect() method of the mon_bio should be called before a read() or write() operation.
MON_BIO_DO_ACCEPTif set, the accept() method of the mon_bio should be called before a read() or write() operation.
MON_BIO_WANT_READif set, the BIO must read more data from the lower levels before it can continue
MON_BIO_WANT_WRITEif 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_READAHEADset the readahead flag to the value of the control's argument (which must be an int *)
MON_BIO_CTL_GET_READAHEADretrieve the value of the read-ahead flag.
MON_BIO_CTL_SINGLESHOT_RESETreset the singleshot indicator so the next read operation may invoke a physical read again
MON_BIO_CTL_CHECK_AUTHSTATEcheck if there is a mon_bio installed that supports transport level authentication.
MON_BIO_CTL_SETUP_AUTHSTATEprepare 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.