Nagios 4.4.14
Dev docs for Nagios core and neb-module hackers
Loading...
Searching...
No Matches
iocache.h
Go to the documentation of this file.
1#ifndef LIBNAGIOS_IOCACHE_H_INCLUDED
2#define LIBNAGIOS_IOCACHE_H_INCLUDED
3#include <stdlib.h>
4#include <sys/types.h>
5#include <sys/socket.h>
6
7/**
8 * @file iocache.h
9 * @brief I/O cache function declarations
10 *
11 * The I/O cache library is useful for reading large chunks of data
12 * from sockets and utilizing parts of that data based on either
13 * size or a magic delimiter.
14 *
15 * @{
16 */
17
18/** opaque type for iocache operations */
19struct iocache;
20typedef struct iocache iocache;
21
22/**
23 * Destroys an iocache object, freeing all memory allocated to it.
24 * @param ioc The iocache object to destroy
25 */
26extern void iocache_destroy(iocache *ioc);
27
28/**
29 * Resets an iocache struct, discarding all data in it without free()'ing
30 * any memory.
31 *
32 * @param[in] ioc The iocache struct to reset
33 */
34extern void iocache_reset(iocache *ioc);
35
36/**
37 * Resizes the buffer in an io cache
38 * @param ioc The io cache to resize
39 * @param new_size The new size of the io cache
40 * @return 0 on success, -1 on errors
41 */
42extern int iocache_resize(iocache *ioc, unsigned long new_size);
43
44/**
45 * Grows an iocache object
46 * This uses iocache_resize() internally
47 * @param[in] ioc The iocache to grow
48 * @param[in] increment How much to increase it
49 * @return 0 on success, -1 on errors
50 */
51extern int iocache_grow(iocache *ioc, unsigned long increment);
52
53/**
54 * Returns the total size of the io cache
55 * @param[in] ioc The iocache to inspect
56 * @return The size of the io cache. If ioc is null, 0 is returned
57 */
58extern unsigned long iocache_size(iocache *ioc);
59
60/**
61 * Returns remaining read capacity of the io cache
62 * @param ioc The io cache to operate on
63 * @return The number of bytes available to read, or -1 if ioc is null, -2 if the buffer is null, or -3 if the buffer size is <= 0
64 */
65extern unsigned long iocache_capacity(iocache *ioc);
66
67/**
68 * Return the amount of unread but stored data in the io cache
69 * @param ioc The io cache to operate on
70 * @return Number of bytes available to read
71 */
72extern unsigned long iocache_available(iocache *ioc);
73
74/**
75 * Use a chunk of data from iocache based on size. The caller
76 * must take care not to write beyond the end of the requested
77 * buffer, or Bad Things(tm) will happen.
78 *
79 * @param ioc The io cache we should use data from
80 * @param size The size of the data we want returned
81 * @return NULL on errors (insufficient data, fe). pointer on success
82 */
83extern char *iocache_use_size(iocache *ioc, unsigned long size);
84
85/**
86 * Use a chunk of data from iocache based on delimiter. The
87 * caller must take care not to write beyond the end of the
88 * requested buffer, if any is returned, or Bad Things(tm) will
89 * happen.
90 *
91 * @param ioc The io cache to use data from
92 * @param delim The delimiter
93 * @param delim_len Length of the delimiter
94 * @param size Length of the returned buffer
95 * @return NULL on errors (delimiter not found, insufficient data). pointer on success
96 */
97extern char *iocache_use_delim(iocache *ioc, const char *delim, size_t delim_len, unsigned long *size);
98
99/**
100 * Forget that a specified number of bytes have been used.
101 * @param ioc The io cache that you want to un-use data in
102 * @param size The number of bytes you want to forget you've seen
103 * @return -1 if there was an error, 0 otherwise.
104 */
105extern int iocache_unuse_size(iocache *ioc, unsigned long size);
106
107/**
108 * Creates the iocache object, initializing it with the given size
109 * @param size Initial size of the iocache buffer
110 * @return Pointer to a valid iocache object
111 */
112extern iocache *iocache_create(unsigned long size);
113
114/**
115 * Read data into the iocache buffer
116 * @param ioc The io cache we should read into
117 * @param fd The filedescriptor we should read from
118 * @return The number of bytes read on success. < 0 on errors
119 */
120extern int iocache_read(iocache *ioc, int fd);
121
122/**
123 * Add data to the iocache buffer
124 * The data is copied, so it can safely be taken from the stack in a
125 * function that returns before the data is used.
126 * If the io cache is too small to hold the data, -1 will be returned.
127 *
128 * @param[in] ioc The io cache to add to
129 * @param[in] buf Pointer to the data we should add
130 * @param[in] len Length (in bytes) of data pointed to by buf
131 * @return iocache_available(ioc) on success, -1 on errors
132 */
133extern int iocache_add(iocache *ioc, char *buf, unsigned int len);
134
135/**
136 * Like sendto(), but sends all cached data prior to the requested
137 *
138 * @param[in] ioc The iocache to send, or cache data in
139 * @param[in] fd The file descriptor to send to
140 * @param[in] buf Pointer to the data to send
141 * @param[in] len Length (in bytes) of data to send
142 * @param[in] flags Flags passed to sendto(2)
143 * @param[in] dest_addr Destination address
144 * @param[in] addrlen size (in bytes) of dest_addr
145 * @return bytes sent on success, -ERRNO on errors
146 */
147extern int iocache_sendto(iocache *ioc, int fd, char *buf, unsigned int len, int flags, const struct sockaddr *dest_addr, socklen_t addrlen);
148
149/**
150 * Like send(2), but sends all cached data prior to the requested
151 * This function uses iocache_sendto() internally, but can only be
152 * used on connected sockets or open()'ed files.
153 *
154 * @param[in] ioc The iocache to send, or cache data in
155 * @param[in] fd The file descriptor to send to
156 * @param[in] buf Pointer to the data to send
157 * @param[in] len Length (in bytes) of data to send
158 * @param[in] flags Flags passed to sendto(2)
159 * @return bytes sent on success, -ERRNO on errors
160 */
161static inline int iocache_send(iocache *ioc, int fd, char *buf, unsigned int len, int flags)
162{
163 return iocache_sendto(ioc, fd, buf, len, flags, NULL, 0);
164}
165
166/**
167 * Like write(2), but sends all cached data prior to the requested
168 * This function uses iocache_send() internally.
169 *
170 * @param[in] ioc The iocache to send, or cache data in
171 * @param[in] fd The file descriptor to send to
172 * @param[in] buf Pointer to the data to send
173 * @param[in] len Length (in bytes) of data to send
174 * @return bytes sent on success, -ERRNO on errors
175 */
176static inline int iocache_write(iocache *ioc, int fd, char *buf, unsigned int len)
177{
178 return iocache_send(ioc, fd, buf, len, 0);
179}
180#endif /* INCLUDE_iocache_h__ */
181/** @} */
unsigned long iocache_size(iocache *ioc)
Returns the total size of the io cache.
int iocache_sendto(iocache *ioc, int fd, char *buf, unsigned int len, int flags, const struct sockaddr *dest_addr, socklen_t addrlen)
Like sendto(), but sends all cached data prior to the requested.
iocache * iocache_create(unsigned long size)
Creates the iocache object, initializing it with the given size.
char * iocache_use_delim(iocache *ioc, const char *delim, size_t delim_len, unsigned long *size)
Use a chunk of data from iocache based on delimiter.
int iocache_unuse_size(iocache *ioc, unsigned long size)
Forget that a specified number of bytes have been used.
unsigned long iocache_capacity(iocache *ioc)
Returns remaining read capacity of the io cache.
int iocache_resize(iocache *ioc, unsigned long new_size)
Resizes the buffer in an io cache.
int iocache_grow(iocache *ioc, unsigned long increment)
Grows an iocache object This uses iocache_resize() internally.
void iocache_reset(iocache *ioc)
Resets an iocache struct, discarding all data in it without free()'ing any memory.
char * iocache_use_size(iocache *ioc, unsigned long size)
Use a chunk of data from iocache based on size.
int iocache_read(iocache *ioc, int fd)
Read data into the iocache buffer.
int iocache_add(iocache *ioc, char *buf, unsigned int len)
Add data to the iocache buffer The data is copied, so it can safely be taken from the stack in a func...
void iocache_destroy(iocache *ioc)
Destroys an iocache object, freeing all memory allocated to it.
unsigned long iocache_available(iocache *ioc)
Return the amount of unread but stored data in the io cache.