---

shbuf.h File Reference

#include <sys/types.h>

Go to the source code of this file.

Data Structures
struct	shbuf_status
	Structure encapsulating the status of a shared buffer. More...
Typedefs
typedef _shbuf	shbuf
	typedef of a shbuf object
Functions
shbuf *	shbuf_create (key_t key, unsigned long size)
	Creates a new shared buffer and returns a shbuf object encapsulating it.
shbuf *	shbuf_open (key_t key)
	Opens an existing shared buffer created by a call to shbuf_create() and returns a shbuf object encapsulating it.
void	shbuf_free (shbuf *sb)
	Frees an opened shared buffer and removes it, when the calling process is the provider.
int	shbuf_access (shbuf *sb, int mode)
	Sets the Unix access mode of the shared buffer.
key_t	shbuf_get_key (shbuf *sb)
	Returns the shared memory key of the shbuf object.
unsigned long	shbuf_get_size (shbuf *sb)
	Returns the size of the shared buffer in bytes.
unsigned char *	shbuf_get_pointer (shbuf *sb)
	Returns a pointer to the shared buffer.
shbuf_status *	shbuf_get_status (shbuf *sb)
	Returns a pointer to the shbuf_status object attached to the shared buffer.
int	shbuf_notify_enable (shbuf *sb, int b)
	Enables or disabled notifying mode.
int	shbuf_notify (shbuf *sb)
	Notifies the other side of the shared buffer.
int	shbuf_wait (shbuf *sb)
	Waits for a notification from the other side of the shared buffer.
int	shbuf_get_select_fd (shbuf *sb)
	Returns the file descriptor the program may select() on for waiting for changes in the buffer.
int	shbuf_post_select (shbuf *sb)
	Cleans up a notifying shbuf.
int	shbuf_status_lock (shbuf *sb)
	Lock the shbuf_status structure attached to the shbuf object.
int	shbuf_status_unlock (shbuf *sb)
	Unlock the shbuf_status structure attached to the shbuf object.
int	shbuf_reset (shbuf *sb)
	Reset the status structure of the shared buffer.
int	shbuf_zero (shbuf *sb)
	Similar to shbuf_reset(), but zeroes the shared buffered completely.
int	shbuf_set_backlog_target (shbuf *sb, unsigned long bl)
	Sets the desired backlog size in bytes.
unsigned long	shbuf_get_backlog_target (shbuf *sb)
	Returns the current desired backlog size in bytes.
const unsigned char *	shbuf_get_read_pointer (shbuf *sb, unsigned long *l)
	Returns a pointer to the next data which may be read from the buffer.
int	shbuf_inc_read_pointer (shbuf *sb, unsigned long r)
	Increments the read index of the shared buffer by a given amount of bytes.
unsigned char *	shbuf_get_write_pointer (shbuf *sb, unsigned long *l)
	Returns a pointer to the next data which may be written to the buffer.
int	shbuf_inc_write_pointer (shbuf *sb, unsigned long r)
	Increments the write index of the shared buffer by a given amount of bytes.
int	shbuf_connected (shbuf *sb)
	Checks whether a client as well as a provider are connected to the the shared buffer.
int	shbuf_is_full (shbuf *sb)
	Checks whether the shared buffer is full.
int	shbuf_is_empty (shbuf *sb)
	Checks whether the shared buffer is empty.
unsigned long	shbuf_rewind (shbuf *sb, unsigned long v)
	Tries to rewind the read index or returns the size of the current backlog.
signed long	shbuf_read (shbuf *sb, unsigned char *c, signed long l)
	A function similar to the C library's read().
signed long	shbuf_write (shbuf *sb, const unsigned char *c, signed long l)
	A function similar to the C library's write().

---

Typedef Documentation

typedef struct _shbuf shbuf

typedef of a shbuf object Definition at line 210 of file shbuf.h.

---

Function Documentation

int shbuf_access (  shbuf *    sb, int    mode )

Sets the Unix access mode of the shared buffer. It defaults to 0700 on creation. Parameters: sb  Pointer to the shbuf object to be changed mode  the Unix access mode Returns: 0 on success, -1 on failure Examples: shbuftest.c.

int shbuf_connected (  shbuf *    sb )

Checks whether a client as well as a provider are connected to the the shared buffer. Parameters: sb  Pointer to the shbuf object Returns: Nonzero when both sides are connected, otherwise zero Examples: shbuftest.c.

shbuf* shbuf_create (  key_t    key, unsigned long    size )

Creates a new shared buffer and returns a shbuf object encapsulating it. The calling process becomes the provider of the buffer. Parameters: key  Desired key, 0 for automatic selection size  The length of the shbuf in byte Returns: Pointer to new shbuf object, or NULL on failure Examples: shbuftest.c.

void shbuf_free (  shbuf *    sb )

Frees an opened shared buffer and removes it, when the calling process is the provider. The shbuf object is freed. Parameters: sb  Pointer to the shbuf object to be removed Examples: shbuftest.c.

unsigned long shbuf_get_backlog_target (  shbuf *    sb )

Returns the current desired backlog size in bytes. This defaults to 0 on newly created shbuf objects. Parameters: sb  Pointer to th shbuf object Returns: (unsigned long) -1 on error, backlog target size in bytes on success

key_t shbuf_get_key (  shbuf *    sb )

Returns the shared memory key of the shbuf object. Parameters: sb  Pointer to the shbuf object Returns: The shared memory key Examples: shbuftest.c.

unsigned char* shbuf_get_pointer (  shbuf *    sb )

Returns a pointer to the shared buffer. It is valid until the shbuf object is freed. Parameters: sb  Pointer to the shbuf object Returns: A pointer to the shared buffer

const unsigned char* shbuf_get_read_pointer (  shbuf *    sb, unsigned long *    l )

Returns a pointer to the next data which may be read from the buffer. Parameters: sb  Pointer to the shbuf object l  Pointer to an unsigned long, where the amount of bytes to be read will be stored. May be NULL. When no data may be read this will be filled be zero. Returns: Pointer to the next bytes to be read, NULL when none are availabled, (unsigned char*) -1 on error. Examples: shbuftest.c.

int shbuf_get_select_fd (  shbuf *    sb )

Returns the file descriptor the program may select() on for waiting for changes in the buffer. Parameters: sb  Pointer to the shbuf object Returns: The file descriptor

unsigned long shbuf_get_size (  shbuf *    sb )

Returns the size of the shared buffer in bytes. Parameters: sb  Pointer to the shbuf object Returns: The size in bytes

shbuf_status* shbuf_get_status (  shbuf *    sb )

Returns a pointer to the shbuf_status object attached to the shared buffer. It is valid until the shbuf object is freed. Parameters: sb  Pointer to the shbuf object Returns: A pointer to the shbuf_status structure

unsigned char* shbuf_get_write_pointer (  shbuf *    sb, unsigned long *    l )

Returns a pointer to the next data which may be written to the buffer. Parameters: sb  Pointer to the shbuf object l  Pointer to an unsigned long, where the amount of bytes to be written will be stored. May be NULL. When no data may be written this will be filled be zero. Returns: Pointer to the next bytes to be written, NULL when none are availabled, (unsigned char*) -1 on error. Examples: shbuftest.c.

int shbuf_inc_read_pointer (  shbuf *    sb, unsigned long    r )

Increments the read index of the shared buffer by a given amount of bytes. Parameters: sb  Pointer to the shbuf object r  Amount of bytes, the index shall be incremented by. Returns: 0 on success, -1 on failure Examples: shbuftest.c.

int shbuf_inc_write_pointer (  shbuf *    sb, unsigned long    r )

Increments the write index of the shared buffer by a given amount of bytes. Parameters: sb  Pointer to the shbuf object r  Amount of bytes, the index shall be incremented by. Returns: 0 on success, -1 on failure Examples: shbuftest.c.

int shbuf_is_empty (  shbuf *    sb )

Checks whether the shared buffer is empty. Parameters: sb  Pointer to the shbuf object Returns: 1 when empty, -1 on error, 0 otherwise

int shbuf_is_full (  shbuf *    sb )

Checks whether the shared buffer is full. Parameters: sb  Pointer to the shbuf object Returns: 1 when full, -1 on error, 0 otherwise

int shbuf_notify (  shbuf *    sb )

Notifies the other side of the shared buffer. A call to this function will be ignored when the other side hasn't enabled notifying mode. Parameters: sb  Pointer to the shbuf object Returns: 0 on success, -1 on failure Examples: shbuftest.c.

int shbuf_notify_enable (  shbuf *    sb, int    b )

Enables or disabled notifying mode. When this is enabled, the process may wait for changes in the buffer with standard select() calls. Parameters: sb  Pointer to the shbuf object b  Notifying mode is enabled when nonzero, it is disabled when zero Returns: 0 on success, -1 on failure Examples: shbuftest.c.

shbuf* shbuf_open (  key_t    key )

Opens an existing shared buffer created by a call to shbuf_create() and returns a shbuf object encapsulating it. The calling process becomes the client of the shbuf. Parameters: key  The key of the shbuf Returns: Pointer to the new shbug object, or NULL on failure See also: shbuf_create Examples: shbuftest.c.

int shbuf_post_select (  shbuf *    sb )

Cleans up a notifying shbuf. Should be called immediately after a select() call for. Otherwise the following call to select() for the file descriptor will succeed immediately. Parameters: sb  Pointer to the shbuf object Returns: 0 on success, -1 on failure

signed long shbuf_read (  shbuf *    sb, unsigned char *    c, signed long    l )

A function similar to the C library's read(). Reads at most l bytes from the shared buffer to c. If not data is available the function blocks. Note: Don't use this function regularly as most of the time the better solution are seperated calls to shbuf_get_read_pointer() and shbuf_inc_read_pointer(): This function uses a memcpy() for copying the data from the shared buffer to c, which is superflous is most cases as it might be a better idea to use the data from the shared buffer directly. Parameters: sb  Pointer to the shbuf object c  Where to read the data to l  How many bytes to read at most? Returns: The number of read bytes or -1 on failure

int shbuf_reset (  shbuf *    sb )

Reset the status structure of the shared buffer. This may be used for emptying the buffer at once. Parameters: sb  Pointer to the shbuf object Returns: 0 on success, -1 on failure

unsigned long shbuf_rewind (  shbuf *    sb, unsigned long    v )

Tries to rewind the read index or returns the size of the current backlog. Parameters: sb  Pointer to the shbuf object v  Specifies how many bytes the read pointer shall be rewinded. If zero, the length of the current backlog is returned. If (unsigned long) -1 the maximum possible rewinding is tried. Returns: The number of bytes the read pointer could be rewinded. This may (and usually is) a smaller value than v. If v was zero, the maxium possible rewinding is returned. (unsigned long) -1 is returned on error.

int shbuf_set_backlog_target (  shbuf *    sb, unsigned long    bl )

Sets the desired backlog size in bytes. Parameters: sb  Pointer to th shbuf object bl  The desired backlog size, clipped when too large Returns: 0 on success, -1 on failure

int shbuf_status_lock (  shbuf *    sb )

Lock the shbuf_status structure attached to the shbuf object. This should be done before accessing any of the member fields. This may block when another process has locked the shared buffer. These locks are not recursive! Parameters: sb  Pointer to the shbuf object to be locked Returns: 0 on success, -1 on failure

int shbuf_status_unlock (  shbuf *    sb )

Unlock the shbuf_status structure attached to the shbuf object. This should be done after accessing any of the member fields. Parameters: sb  Pointer to the shbuf object to be unlocked Returns: 0 on success, -1 on failure

int shbuf_wait (  shbuf *    sb )

Waits for a notification from the other side of the shared buffer. This call doesn't do anything more than calling select() with the correct parameters. Parameters: sb  Pointer to the shbuf object Returns: 0 on success, -1 on failure Examples: shbuftest.c.

signed long shbuf_write (  shbuf *    sb, const unsigned char *    c, signed long    l )

A function similar to the C library's write(). Writes at most l bytes from c to the shared buffer. If no data can be written the function blocks. Note: Don't use this function regularly as most of the time the better solution are seperated calls to shbuf_get_write_pointer() and shbuf_inc_write_pointer(): This function uses a memcpy() for copying the data from c to the shared buffer, which is superflous is most cases as it might be a better idea to use the data from the shared buffer directly. Parameters: sb  Pointer to the shbuf object c  Where to write the data from l  How many bytes to write at most? Returns: The number of written bytes or -1 on failure

int shbuf_zero (  shbuf *    sb )

Similar to shbuf_reset(), but zeroes the shared buffered completely. Parameters: sb  Pointer to the shbuf object Returns: 0 on success, -1 on failure

---