Nagios 4.5.4
Dev docs for Nagios core and neb-module hackers
Loading...
Searching...
No Matches
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 /* there is data to read */
 
#define IOBROKER_POLLPRI   0x002 /* there is urgent data to read */
 
#define IOBROKER_POLLOUT   0x004 /* writing now will not block */
 
#define IOBROKER_POLLERR   0x008 /* error condition */
 
#define IOBROKER_POLLHUP   0x010 /* hung up */
 
#define IOBROKER_POLLNVAL   0x020 /* invalid polling request */
 
#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

◆ iobroker_close()

int iobroker_close ( iobroker_set * iobs,
int sd )
extern

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
iobsThe socket set to remove the socket from
sdThe socket descriptor to remove and close
Returns
0 on success. < 0 on errors

◆ iobroker_create()

iobroker_set * iobroker_create ( void )
extern

Create a new socket set.

Returns
An iobroker_set on success. NULL on errors.

◆ iobroker_deregister()

int iobroker_deregister ( iobroker_set * iobs,
int sd )
extern

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

Parameters
iobsThe socket set to remove the socket from
sdThe socket descriptor to remove
Returns
0 on success. < 0 on errors.

◆ iobroker_destroy()

void iobroker_destroy ( iobroker_set * iobs,
int flags )
extern

Destroy a socket set as created by iobroker_create.

Parameters
iobsThe socket set to destroy
flagsIf set, close(2) all registered sockets

◆ iobroker_get_max_fds()

int iobroker_get_max_fds ( iobroker_set * iobs)
extern

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

Parameters
iobsThe io broker set to query
Returns
Max file descriptor capacity for the set

◆ iobroker_get_num_fds()

int iobroker_get_num_fds ( iobroker_set * iobs)
extern

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

Parameters
iobsThe io broker set to query
Returns
Number of file descriptors registered in the set

◆ iobroker_is_registered()

int iobroker_is_registered ( iobroker_set * iobs,
int fd )
extern

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

Parameters
[in]iobsThe iobroker set the filedescriptor should be member of
[in]fdThe filedescriptor to check for
Returns
1 if the filedescriptor is registered and 0 otherwise

◆ iobroker_max_usable_fds()

int iobroker_max_usable_fds ( void )
extern

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

◆ iobroker_poll()

int iobroker_poll ( iobroker_set * iobs,
int timeout )
extern

Wait for input on any of the registered sockets.

Parameters
iobsThe socket set to wait for.
timeoutTimeout in milliseconds. -1 is "wait indefinitely"
Returns
-1 on errors, or number of filedescriptors with input

◆ iobroker_register()

int iobroker_register ( iobroker_set * iobs,
int sd,
void * arg,
int(* handler )(int, int, void *) )
extern

Register a socket for input polling with the broker.

Parameters
iobsThe socket set to add the socket to.
sdThe socket descriptor to add
argArgument passed to input handler on available input
handlerThe callback function to call when input is available
Returns
0 on success. < 0 on errors.

◆ iobroker_register_out()

int iobroker_register_out ( iobroker_set * iobs,
int sd,
void * arg,
int(* handler )(int, int, void *) )
extern

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
iobsThe socket set to add the socket to.
sdThe socket descriptor to add
argArgument passed to output handler on ready-to-write
handlerThe function to call when output won't block
Returns
0 on success. < 0 on errors

◆ iobroker_strerror()

const char * iobroker_strerror ( int error)
extern

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

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

Parameters
errorThe error code
Returns
A string describing the meaning of the error code

◆ iobroker_unregister()

int iobroker_unregister ( iobroker_set * iobs,
int sd )
extern

Unregister a socket for input polling with the broker.

Parameters
iobsThe socket set to remove the socket from
sdThe socket descriptor to remove
Returns
0 on success. < 0 on errors.