iobroker.h File Reference

I/O broker library function declarations. More...

Go to the source code of this file.



#define IOBROKER_USES_EPOLL   1
#define IOBROKER_POLLIN   0x001
#define IOBROKER_POLLPRI   0x002
#define IOBROKER_POLLOUT   0x004
#define IOBROKER_POLLERR   0x008
#define IOBROKER_POLLHUP   0x010
#define IOBROKER_POLLNVAL   0x020
#define IOBROKER_SUCCESS   0
 return codes
#define IOBROKER_ENOSET   (-1)
#define IOBROKER_ENOINIT   (-2)
#define IOBROKER_ELIB   (-3)
#define IOBROKER_EALREADY   (-EALREADY)
#define IOBROKER_EINVAL   (-EINVAL)
#define IOBROKER_CLOSE_SOCKETS   1
 Flags for iobroker_destroy().
typedef struct iobroker_set iobroker_set
const char * iobroker_strerror (int error)
 Get a string describing the error in the last iobroker call.
iobroker_set * iobroker_create (void)
 Create a new socket set.
int iobroker_max_usable_fds (void)
 Published utility function used to determine the max number of file descriptors this process can keep open at any one time.
int iobroker_register (iobroker_set *iobs, int sd, void *arg, int(*handler)(int, int, void *))
 Register a socket for input polling with the broker.
int iobroker_register_out (iobroker_set *iobs, int sd, void *arg, int(*handler)(int, int, void *))
 Register a socket for output polling with the broker.
int iobroker_is_registered (iobroker_set *iobs, int fd)
 Check if a particular filedescriptor is registered with the iobroker set.
int iobroker_get_num_fds (iobroker_set *iobs)
 Getter function for number of file descriptors registered in the set specified.
int iobroker_get_max_fds (iobroker_set *iobs)
 Getter function for the maximum amount of file descriptors this set can handle.
int iobroker_unregister (iobroker_set *iobs, int sd)
 Unregister a socket for input polling with the broker.
int iobroker_deregister (iobroker_set *iobs, int sd)
 Deregister a socket for input polling with the broker (this is identical to iobroker_unregister()).
int iobroker_close (iobroker_set *iobs, int sd)
 Unregister and close(2) a socket registered for input with the broker.
void iobroker_destroy (iobroker_set *iobs, int flags)
 Destroy a socket set as created by iobroker_create.
int iobroker_poll (iobroker_set *iobs, int timeout)
 Wait for input on any of the registered sockets.

Detailed Description

I/O broker library function declarations.

The I/O broker library handles multiplexing between hundreds or thousands of sockets with a few simple calls. It's designed to be as lightweight as possible so as to not cause memory bloat, and is therefore highly suitable for use by processes that are fork()-intensive.


Function Documentation

int iobroker_close ( iobroker_set *  iobs,
int  sd 
)

Unregister and close(2) a socket registered for input with the broker.

This is a convenience function which exists only to avoid doing multiple calls when read() returns 0, as closed sockets must always be removed from the socket set to avoid consuming tons of cpu power from iterating "too fast" over the file descriptors.

Parameters:
iobs The socket set to remove the socket from
sd The socket descriptor to remove and close
Returns:
0 on success. < 0 on errors
iobroker_set* iobroker_create ( void   ) 

Create a new socket set.

Returns:
An iobroker_set on success. NULL on errors.
int iobroker_deregister ( iobroker_set *  iobs,
int  sd 
)

Deregister a socket for input polling with the broker (this is identical to iobroker_unregister()).

Parameters:
iobs The socket set to remove the socket from
sd The socket descriptor to remove
Returns:
0 on success. < 0 on errors.
void iobroker_destroy ( iobroker_set *  iobs,
int  flags 
)

Destroy a socket set as created by iobroker_create.

Parameters:
iobs The socket set to destroy
flags If set, close(2) all registered sockets
int iobroker_get_max_fds ( iobroker_set *  iobs  ) 

Getter function for the maximum amount of file descriptors this set can handle.

Parameters:
iobs The io broker set to query
Returns:
Max file descriptor capacity for the set
int iobroker_get_num_fds ( iobroker_set *  iobs  ) 

Getter function for number of file descriptors registered in the set specified.

Parameters:
iobs The io broker set to query
Returns:
Number of file descriptors registered in the set
int iobroker_is_registered ( iobroker_set *  iobs,
int  fd 
)

Check if a particular filedescriptor is registered with the iobroker set.

Parameters:
[in] iobs The iobroker set the filedescriptor should be member of
[in] fd The filedescriptor to check for
Returns:
1 if the filedescriptor is registered and 0 otherwise
int iobroker_max_usable_fds ( void   ) 

Published utility function used to determine the max number of file descriptors this process can keep open at any one time.

Returns:
Max number of filedescriptors we can keep open
int iobroker_poll ( iobroker_set *  iobs,
int  timeout 
)

Wait for input on any of the registered sockets.

Parameters:
iobs The socket set to wait for.
timeout Timeout in milliseconds. -1 is "wait indefinitely"
Returns:
-1 on errors, or number of filedescriptors with input
int iobroker_register ( iobroker_set *  iobs,
int  sd,
void *  arg,
int(*)(int, int, void *)  handler 
)

Register a socket for input polling with the broker.

Parameters:
iobs The socket set to add the socket to.
sd The socket descriptor to add
arg Argument passed to input handler on available input
handler The callback function to call when input is available
Returns:
0 on succes. < 0 on errors.
int iobroker_register_out ( iobroker_set *  iobs,
int  sd,
void *  arg,
int(*)(int, int, void *)  handler 
)

Register a socket for output polling with the broker.

Note:
There's no guarantee that *ALL* data is writable just because the socket won't block you completely.
Parameters:
iobs The socket set to add the socket to.
sd The socket descriptor to add
arg Argument passed to output handler on ready-to-write
handler The function to call when output won't block
Returns:
0 on success. < 0 on errors
const char* iobroker_strerror ( int  error  ) 

Get a string describing the error in the last iobroker call.

The returned string must not be free()'d.

Parameters:
error The error code
Returns:
A string describing the meaning of the error code
int iobroker_unregister ( iobroker_set *  iobs,
int  sd 
)

Unregister a socket for input polling with the broker.

Parameters:
iobs The socket set to remove the socket from
sd The socket descriptor to remove
Returns:
0 on succes. < 0 on errors.
 All Data Structures Files Functions Variables Typedefs Defines

Generated on 14 Aug 2014 for Nagios by  doxygen 1.6.1