Nagios  4.3.4
Dev docs for Nagios core and neb-module hackers
iocache.h File Reference

I/O cache function declarations. More...

#include <stdlib.h>
#include <sys/types.h>
#include <sys/socket.h>

Go to the source code of this file.

typedef struct iocache iocache
 
void iocache_destroy (iocache *ioc)
 Destroys an iocache object, freeing all memory allocated to it. More...
 
void iocache_reset (iocache *ioc)
 Resets an iocache struct, discarding all data in it without free()'ing any memory. More...
 
int iocache_resize (iocache *ioc, unsigned long new_size)
 Resizes the buffer in an io cache. More...
 
int iocache_grow (iocache *ioc, unsigned long increment)
 Grows an iocache object This uses iocache_resize() internally. More...
 
unsigned long iocache_size (iocache *ioc)
 Returns the total size of the io cache. More...
 
unsigned long iocache_capacity (iocache *ioc)
 Returns remaining read capacity of the io cache. More...
 
unsigned long iocache_available (iocache *ioc)
 Return the amount of unread but stored data in the io cache. More...
 
char * iocache_use_size (iocache *ioc, unsigned long size)
 Use a chunk of data from iocache based on size. More...
 
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. More...
 
int iocache_unuse_size (iocache *ioc, unsigned long size)
 Forget that a specified number of bytes have been used. More...
 
iocache * iocache_create (unsigned long size)
 Creates the iocache object, initializing it with the given size. More...
 
int iocache_read (iocache *ioc, int fd)
 Read data into the iocache buffer. More...
 
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 function that returns before the data is used. More...
 
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. More...
 

Detailed Description

I/O cache function declarations.

The I/O cache library is useful for reading large chunks of data from sockets and utilizing parts of that data based on either size or a magic delimiter.

Function Documentation

◆ iocache_add()

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 function that returns before the data is used.

If the io cache is too small to hold the data, -1 will be returned.

Parameters
[in]iocThe io cache to add to
[in]bufPointer to the data we should add
[in]lenLength (in bytes) of data pointed to by buf
Returns
iocache_available(ioc) on success, -1 on errors

◆ iocache_available()

unsigned long iocache_available ( iocache *  ioc)

Return the amount of unread but stored data in the io cache.

Parameters
iocThe io cache to operate on
Returns
Number of bytes available to read

◆ iocache_capacity()

unsigned long iocache_capacity ( iocache *  ioc)

Returns remaining read capacity of the io cache.

Parameters
iocThe io cache to operate on
Returns
The number of bytes available to read

◆ iocache_create()

iocache* iocache_create ( unsigned long  size)

Creates the iocache object, initializing it with the given size.

Parameters
sizeInitial size of the iocache buffer
Returns
Pointer to a valid iocache object

◆ iocache_destroy()

void iocache_destroy ( iocache *  ioc)

Destroys an iocache object, freeing all memory allocated to it.

Parameters
iocThe iocache object to destroy

◆ iocache_grow()

int iocache_grow ( iocache *  ioc,
unsigned long  increment 
)

Grows an iocache object This uses iocache_resize() internally.

Parameters
[in]iocThe iocache to grow
[in]incrementHow much to increase it
Returns
0 on success, -1 on errors

◆ iocache_read()

int iocache_read ( iocache *  ioc,
int  fd 
)

Read data into the iocache buffer.

Parameters
iocThe io cache we should read into
fdThe filedescriptor we should read from
Returns
The number of bytes read on success. < 0 on errors

◆ iocache_reset()

void iocache_reset ( iocache *  ioc)

Resets an iocache struct, discarding all data in it without free()'ing any memory.

Parameters
[in]iocThe iocache struct to reset

◆ iocache_resize()

int iocache_resize ( iocache *  ioc,
unsigned long  new_size 
)

Resizes the buffer in an io cache.

Parameters
iocThe io cache to resize
new_sizeThe new size of the io cache
Returns
0 on success, -1 on errors

◆ iocache_sendto()

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.

Parameters
[in]iocThe iocache to send, or cache data in
[in]fdThe file descriptor to send to
[in]bufPointer to the data to send
[in]lenLength (in bytes) of data to send
[in]flagsFlags passed to sendto(2)
[in]dest_addrDestination address
[in]addrlensize (in bytes) of dest_addr
Returns
bytes sent on success, -ERRNO on errors

◆ iocache_size()

unsigned long iocache_size ( iocache *  ioc)

Returns the total size of the io cache.

Parameters
[in]iocThe iocache to inspect
Returns
The size of the io cache. If ioc is null, 0 is returned

◆ iocache_unuse_size()

int iocache_unuse_size ( iocache *  ioc,
unsigned long  size 
)

Forget that a specified number of bytes have been used.

Parameters
iocThe io cache that you want to un-use data in
sizeThe number of bytes you want to forget you've seen
Returns
-1 if there was an error, 0 otherwise.

◆ iocache_use_delim()

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.

The caller must take care not to write beyond the end of the requested buffer, if any is returned, or Bad Things(tm) will happen.

Parameters
iocThe io cache to use data from
delimThe delimiter
delim_lenLength of the delimiter
sizeLength of the returned buffer
Returns
NULL on errors (delimiter not found, insufficient data). pointer on success

◆ iocache_use_size()

char* iocache_use_size ( iocache *  ioc,
unsigned long  size 
)

Use a chunk of data from iocache based on size.

The caller must take care not to write beyond the end of the requested buffer, or Bad Things(tm) will happen.

Parameters
iocThe io cache we should use data from
sizeThe size of the data we want returned
Returns
NULL on errors (insufficient data, fe). pointer on success