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