00001 /* lib/iobroker.h. Generated from iobroker.h.in by configure. */ 00002 #ifndef LIBNAGIOS_iobroker_h__ 00003 #define LIBNAGIOS_iobroker_h__ 00004 00005 /** 00006 * @file iobroker.h 00007 * @brief I/O broker library function declarations 00008 * 00009 * The I/O broker library handles multiplexing between hundreds or 00010 * thousands of sockets with a few simple calls. It's designed to 00011 * be as lightweight as possible so as to not cause memory bloat, 00012 * and is therefore highly suitable for use by processes that are 00013 * fork()-intensive. 00014 * 00015 * @{ 00016 */ 00017 00018 #define IOBROKER_USES_EPOLL 1 00019 /* #undef IOBROKER_USES_POLL */ 00020 /* #undef IOBROKER_USES_SELECT */ 00021 00022 #if (_POSIX_C_SOURCE - 0) >= 200112L 00023 #include <poll.h> 00024 # define IOBROKER_POLLIN POLLIN 00025 # define IOBROKER_POLLPRI POLLPRI 00026 # define IOBROKER_POLLOUT POLLOUT 00027 00028 # define IOBROKER_POLLERR POLLERR 00029 # define IOBROKER_POLLHUP POLLHUP 00030 # define IOBROKER_POLLNVAL POLLNVAL 00031 #else 00032 # define IOBROKER_POLLIN 0x001 /* there is data to read */ 00033 # define IOBROKER_POLLPRI 0x002 /* there is urgent data to read */ 00034 # define IOBROKER_POLLOUT 0x004 /* writing now will not block */ 00035 00036 # define IOBROKER_POLLERR 0x008 /* error condition */ 00037 # define IOBROKER_POLLHUP 0x010 /* hung up */ 00038 # define IOBROKER_POLLNVAL 0x020 /* invalid polling request */ 00039 #endif 00040 00041 /** return codes */ 00042 #define IOBROKER_SUCCESS 0 00043 #define IOBROKER_ENOSET (-1) 00044 #define IOBROKER_ENOINIT (-2) 00045 #define IOBROKER_ELIB (-3) 00046 #define IOBROKER_EALREADY (-EALREADY) 00047 #define IOBROKER_EINVAL (-EINVAL) 00048 00049 00050 /** Flags for iobroker_destroy() */ 00051 #define IOBROKER_CLOSE_SOCKETS 1 00052 00053 /* Opaque type. Callers needn't worry about this */ 00054 struct iobroker_set; 00055 typedef struct iobroker_set iobroker_set; 00056 00057 /** 00058 * Get a string describing the error in the last iobroker call. 00059 * The returned string must not be free()'d. 00060 * @param error The error code 00061 * @return A string describing the meaning of the error code 00062 */ 00063 extern const char *iobroker_strerror(int error); 00064 00065 /** 00066 * Create a new socket set 00067 * @return An iobroker_set on success. NULL on errors. 00068 */ 00069 extern iobroker_set *iobroker_create(void); 00070 00071 /** 00072 * Published utility function used to determine the max number of 00073 * file descriptors this process can keep open at any one time. 00074 * @return Max number of filedescriptors we can keep open 00075 */ 00076 extern int iobroker_max_usable_fds(void); 00077 00078 /** 00079 * Register a socket for input polling with the broker. 00080 * 00081 * @param iobs The socket set to add the socket to. 00082 * @param sd The socket descriptor to add 00083 * @param arg Argument passed to input handler on available input 00084 * @param handler The callback function to call when input is available 00085 * 00086 * @return 0 on success. < 0 on errors. 00087 */ 00088 extern int iobroker_register(iobroker_set *iobs, int sd, void *arg, int (*handler)(int, int, void *)); 00089 00090 00091 /** 00092 * Register a socket for output polling with the broker 00093 * @note There's no guarantee that *ALL* data is writable just 00094 * because the socket won't block you completely. 00095 * 00096 * @param iobs The socket set to add the socket to. 00097 * @param sd The socket descriptor to add 00098 * @param arg Argument passed to output handler on ready-to-write 00099 * @param handler The function to call when output won't block 00100 * 00101 * @return 0 on success. < 0 on errors 00102 */ 00103 extern int iobroker_register_out(iobroker_set *iobs, int sd, void *arg, int (*handler)(int, int, void *)); 00104 00105 /** 00106 * Check if a particular filedescriptor is registered with the iobroker set 00107 * @param[in] iobs The iobroker set the filedescriptor should be member of 00108 * @param[in] fd The filedescriptor to check for 00109 * @return 1 if the filedescriptor is registered and 0 otherwise 00110 */ 00111 extern int iobroker_is_registered(iobroker_set *iobs, int fd); 00112 00113 /** 00114 * Getter function for number of file descriptors registered in 00115 * the set specified. 00116 * @param iobs The io broker set to query 00117 * @return Number of file descriptors registered in the set 00118 */ 00119 extern int iobroker_get_num_fds(iobroker_set *iobs); 00120 00121 /** 00122 * Getter function for the maximum amount of file descriptors this 00123 * set can handle. 00124 * @param iobs The io broker set to query 00125 * @return Max file descriptor capacity for the set 00126 */ 00127 extern int iobroker_get_max_fds(iobroker_set *iobs); 00128 00129 /** 00130 * Unregister a socket for input polling with the broker. 00131 * 00132 * @param iobs The socket set to remove the socket from 00133 * @param sd The socket descriptor to remove 00134 * @return 0 on success. < 0 on errors. 00135 */ 00136 extern int iobroker_unregister(iobroker_set *iobs, int sd); 00137 00138 /** 00139 * Deregister a socket for input polling with the broker 00140 * (this is identical to iobroker_unregister()) 00141 * @param iobs The socket set to remove the socket from 00142 * @param sd The socket descriptor to remove 00143 * @return 0 on success. < 0 on errors. 00144 */ 00145 extern int iobroker_deregister(iobroker_set *iobs, int sd); 00146 00147 /** 00148 * Unregister and close(2) a socket registered for input with the 00149 * broker. This is a convenience function which exists only to avoid 00150 * doing multiple calls when read() returns 0, as closed sockets must 00151 * always be removed from the socket set to avoid consuming tons of 00152 * cpu power from iterating "too fast" over the file descriptors. 00153 * 00154 * @param iobs The socket set to remove the socket from 00155 * @param sd The socket descriptor to remove and close 00156 * @return 0 on success. < 0 on errors 00157 */ 00158 extern int iobroker_close(iobroker_set *iobs, int sd); 00159 00160 /** 00161 * Destroy a socket set as created by iobroker_create 00162 * @param iobs The socket set to destroy 00163 * @param flags If set, close(2) all registered sockets 00164 */ 00165 extern void iobroker_destroy(iobroker_set *iobs, int flags); 00166 00167 /** 00168 * Wait for input on any of the registered sockets. 00169 * @param iobs The socket set to wait for. 00170 * @param timeout Timeout in milliseconds. -1 is "wait indefinitely" 00171 * @return -1 on errors, or number of filedescriptors with input 00172 */ 00173 extern int iobroker_poll(iobroker_set *iobs, int timeout); 00174 #endif /* INCLUDE_iobroker_h__ */ 00175 /** @} */