Nagios  4.4.6
Dev docs for Nagios core and neb-module hackers
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 */
54 struct iobroker_set;
55 typedef 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  */
63 extern 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  */
69 extern 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  */
76 extern 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  */
88 extern 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  */
103 extern 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  */
111 extern 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  */
119 extern 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  */
127 extern 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  */
136 extern 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  */
145 extern 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  */
158 extern 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  */
165 extern 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  */
173 extern int iobroker_poll(iobroker_set *iobs, int timeout);
174 #endif /* INCLUDE_iobroker_h__ */
175 /** @} */
iobroker_register_out
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.
iobroker_strerror
const char * iobroker_strerror(int error)
Get a string describing the error in the last iobroker call.
iobroker_is_registered
int iobroker_is_registered(iobroker_set *iobs, int fd)
Check if a particular filedescriptor is registered with the iobroker set.
iobroker_max_usable_fds
int iobroker_max_usable_fds(void)
Published utility function used to determine the max number of file descriptors this process can keep...
iobroker_deregister
int iobroker_deregister(iobroker_set *iobs, int sd)
Deregister a socket for input polling with the broker (this is identical to iobroker_unregister())
iobroker_register
int iobroker_register(iobroker_set *iobs, int sd, void *arg, int(*handler)(int, int, void *))
Register a socket for input polling with the broker.
iobroker_poll
int iobroker_poll(iobroker_set *iobs, int timeout)
Wait for input on any of the registered sockets.
iobroker_destroy
void iobroker_destroy(iobroker_set *iobs, int flags)
Destroy a socket set as created by iobroker_create.
iobroker_get_max_fds
int iobroker_get_max_fds(iobroker_set *iobs)
Getter function for the maximum amount of file descriptors this set can handle.
iobroker_create
iobroker_set * iobroker_create(void)
Create a new socket set.
iobroker_unregister
int iobroker_unregister(iobroker_set *iobs, int sd)
Unregister a socket for input polling with the broker.
iobroker_get_num_fds
int iobroker_get_num_fds(iobroker_set *iobs)
Getter function for number of file descriptors registered in the set specified.
iobroker_close
int iobroker_close(iobroker_set *iobs, int sd)
Unregister and close(2) a socket registered for input with the broker.