Nagios  4.3.4
Dev docs for Nagios core and neb-module hackers
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 */
19 struct iocache;
20 typedef 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  */
26 extern 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  */
34 extern 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  */
42 extern 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  */
51 extern 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  */
58 extern 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
64  */
65 extern 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  */
72 extern 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  */
83 extern 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  */
97 extern 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  */
105 extern 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  */
112 extern 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  */
120 extern 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  */
133 extern 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  */
147 extern 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  */
161 static 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  */
176 static 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 /** @} */
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.
void iocache_destroy(iocache *ioc)
Destroys an iocache object, freeing all memory allocated to it.
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...
unsigned long iocache_size(iocache *ioc)
Returns the total size of the io cache.
int iocache_resize(iocache *ioc, unsigned long new_size)
Resizes the buffer in an io cache.
void iocache_reset(iocache *ioc)
Resets an iocache struct, discarding all data in it without free()&#39;ing any memory.
unsigned long iocache_capacity(iocache *ioc)
Returns remaining read capacity of the io cache.
int iocache_read(iocache *ioc, int fd)
Read data into the iocache buffer.
char * iocache_use_size(iocache *ioc, unsigned long size)
Use a chunk of data from iocache based on size.
int iocache_unuse_size(iocache *ioc, unsigned long size)
Forget that a specified number of bytes have been used.
unsigned long iocache_available(iocache *ioc)
Return the amount of unread but stored data in the io cache.
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_grow(iocache *ioc, unsigned long increment)
Grows an iocache object This uses iocache_resize() internally.