Nagios  4.0.1
Dev docs for Nagios core and neb-module hackers
 All Data Structures Files Functions Variables Typedefs Macros Pages
iobroker.h
Go to the documentation of this file.
1 #ifndef LIBNAGIOS_iobroker_h__
2 #define LIBNAGIOS_iobroker_h__
3 
4 /**
5  * @file iobroker.h
6  * @brief I/O broker library function declarations
7  *
8  * The I/O broker library handles multiplexing between hundreds or
9  * thousands of sockets with a few simple calls. It's designed to
10  * be as lightweight as possible so as to not cause memory bloat,
11  * and is therefore highly suitable for use by processes that are
12  * fork()-intensive.
13  *
14  * @{
15  */
16 
17 #if (_POSIX_C_SOURCE - 0) >= 200112L
18 #include <poll.h>
19 # define IOBROKER_POLLIN POLLIN
20 # define IOBROKER_POLLPRI POLLPRI
21 # define IOBROKER_POLLOUT POLLOUT
22 
23 # define IOBROKER_POLLERR POLLERR
24 # define IOBROKER_POLLHUP POLLHUP
25 # define IOBROKER_POLLNVAL POLLNVAL
26 #else
27 # define IOBROKER_POLLIN 0x001 /* there is data to read */
28 # define IOBROKER_POLLPRI 0x002 /* there is urgent data to read */
29 # define IOBROKER_POLLOUT 0x004 /* writing now will not block */
30 
31 # define IOBROKER_POLLERR 0x008 /* error condition */
32 # define IOBROKER_POLLHUP 0x010 /* hung up */
33 # define IOBROKER_POLLNVAL 0x020 /* invalid polling request */
34 #endif
35 
36 /** return codes */
37 #define IOBROKER_SUCCESS 0
38 #define IOBROKER_ENOSET (-1)
39 #define IOBROKER_ENOINIT (-2)
40 #define IOBROKER_ELIB (-3)
41 #define IOBROKER_EALREADY (-EALREADY)
42 #define IOBROKER_EINVAL (-EINVAL)
43 
44 
45 /** Flags for iobroker_destroy() */
46 #define IOBROKER_CLOSE_SOCKETS 1
47 
48 /* Opaque type. Callers needn't worry about this */
49 struct iobroker_set;
50 typedef struct iobroker_set iobroker_set;
51 
52 /**
53  * Get a string describing the error in the last iobroker call.
54  * The returned string must not be free()'d.
55  * @param error The error code
56  * @return A string describing the meaning of the error code
57  */
58 extern const char *iobroker_strerror(int error);
59 
60 /**
61  * Create a new socket set
62  * @return An iobroker_set on success. NULL on errors.
63  */
64 extern iobroker_set *iobroker_create(void);
65 
66 /**
67  * Published utility function used to determine the max number of
68  * file descriptors this process can keep open at any one time.
69  * @return Max number of filedescriptors we can keep open
70  */
71 extern int iobroker_max_usable_fds(void);
72 
73 /**
74  * Register a socket for input polling with the broker.
75  *
76  * @param iobs The socket set to add the socket to.
77  * @param sd The socket descriptor to add
78  * @param arg Argument passed to input handler on available input
79  * @param handler The callback function to call when input is available
80  *
81  * @return 0 on succes. < 0 on errors.
82  */
83 extern int iobroker_register(iobroker_set *iobs, int sd, void *arg, int (*handler)(int, int, void *));
84 
85 
86 /**
87  * Register a socket for output polling with the broker
88  * @note There's no guarantee that *ALL* data is writable just
89  * because the socket won't block you completely.
90  *
91  * @param iobs The socket set to add the socket to.
92  * @param sd The socket descriptor to add
93  * @param arg Argument passed to output handler on ready-to-write
94  * @param handler The function to call when output won't block
95  *
96  * @return 0 on success. < 0 on errors
97  */
98 extern int iobroker_register_out(iobroker_set *iobs, int sd, void *arg, int (*handler)(int, int, void *));
99 
100 /**
101  * Check if a particular filedescriptor is registered with the iobroker set
102  * @param[in] iobs The iobroker set the filedescriptor should be member of
103  * @param[in] fd The filedescriptor to check for
104  * @return 1 if the filedescriptor is registered and 0 otherwise
105  */
106 extern int iobroker_is_registered(iobroker_set *iobs, int fd);
107 
108 /**
109  * Getter function for number of file descriptors registered in
110  * the set specified.
111  * @param iobs The io broker set to query
112  * @return Number of file descriptors registered in the set
113  */
114 extern int iobroker_get_num_fds(iobroker_set *iobs);
115 
116 /**
117  * Getter function for the maximum amount of file descriptors this
118  * set can handle.
119  * @param iobs The io broker set to query
120  * @return Max file descriptor capacity for the set
121  */
122 extern int iobroker_get_max_fds(iobroker_set *iobs);
123 
124 /**
125  * Unregister a socket for input polling with the broker.
126  *
127  * @param iobs The socket set to remove the socket from
128  * @param sd The socket descriptor to remove
129  * @return 0 on succes. < 0 on errors.
130  */
131 extern int iobroker_unregister(iobroker_set *iobs, int sd);
132 
133 /**
134  * Deregister a socket for input polling with the broker
135  * (this is identical to iobroker_unregister())
136  * @param iobs The socket set to remove the socket from
137  * @param sd The socket descriptor to remove
138  * @return 0 on success. < 0 on errors.
139  */
140 extern int iobroker_deregister(iobroker_set *iobs, int sd);
141 
142 /**
143  * Unregister and close(2) a socket registered for input with the
144  * broker. This is a convenience function which exists only to avoid
145  * doing multiple calls when read() returns 0, as closed sockets must
146  * always be removed from the socket set to avoid consuming tons of
147  * cpu power from iterating "too fast" over the file descriptors.
148  *
149  * @param iobs The socket set to remove the socket from
150  * @param sd The socket descriptor to remove and close
151  * @return 0 on success. < 0 on errors
152  */
153 extern int iobroker_close(iobroker_set *iobs, int sd);
154 
155 /**
156  * Destroy a socket set as created by iobroker_create
157  * @param iobs The socket set to destroy
158  * @param flags If set, close(2) all registered sockets
159  */
160 extern void iobroker_destroy(iobroker_set *iobs, int flags);
161 
162 /**
163  * Wait for input on any of the registered sockets.
164  * @param iobs The socket set to wait for.
165  * @param timeout Timeout in milliseconds. -1 is "wait indefinitely"
166  * @return -1 on errors, or number of filedescriptors with input
167  */
168 extern int iobroker_poll(iobroker_set *iobs, int timeout);
169 #endif /* INCLUDE_iobroker_h__ */
170 /** @} */
int iobroker_get_num_fds(iobroker_set *iobs)
Getter function for number of file descriptors registered in the set specified.
const char * iobroker_strerror(int error)
Get a string describing the error in the last iobroker call.
int iobroker_poll(iobroker_set *iobs, int timeout)
Wait for input on any of the registered sockets.
int iobroker_get_max_fds(iobroker_set *iobs)
Getter function for the maximum amount of file descriptors this set can handle.
iobroker_set * iobroker_create(void)
Create a new socket set.
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_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_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_unregister(iobroker_set *iobs, int sd)
Unregister a socket for input polling with the broker.
int iobroker_max_usable_fds(void)
Published utility function used to determine the max number of file descriptors this process can keep...
int iobroker_is_registered(iobroker_set *iobs, int fd)
Check if a particular filedescriptor is registered with the iobroker set.
int iobroker_deregister(iobroker_set *iobs, int sd)
Deregister a socket for input polling with the broker (this is identical to iobroker_unregister()) ...