Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NAL_BUFFER_NEW(2)		   distcache		     NAL_BUFFER_NEW(2)

NAME
       NAL_BUFFER_new, NAL_BUFFER_free,	NAL_BUFFER_set_size, NAL_BUFFER_empty,
       NAL_BUFFER_full,	NAL_BUFFER_notempty, NAL_BUFFER_notfull, NAL_BUF-
       FER_used, NAL_BUFFER_unused, NAL_BUFFER_data, NAL_BUFFER_size, NAL_BUF-
       FER_write, NAL_BUFFER_read, NAL_BUFFER_write_ptr, NAL_BUFFER_takedata,
       NAL_BUFFER_wrote	- libnal buffer	functions

SYNOPSIS
	#include <libnal/nal.h>

	NAL_BUFFER *NAL_BUFFER_new(void);
	void NAL_BUFFER_free(NAL_BUFFER	*buf);
	void NAL_BUFFER_reset(NAL_BUFFER *buf);
	int NAL_BUFFER_set_size(NAL_BUFFER *buf, unsigned int size);
	int NAL_BUFFER_empty(const NAL_BUFFER *buf);
	int NAL_BUFFER_full(const NAL_BUFFER *buf);
	int NAL_BUFFER_notempty(const NAL_BUFFER *buf);
	int NAL_BUFFER_notfull(const NAL_BUFFER	*buf);
	unsigned int NAL_BUFFER_used(const NAL_BUFFER *buf);
	unsigned int NAL_BUFFER_unused(const NAL_BUFFER	*buf);
	unsigned int NAL_BUFFER_size(const NAL_BUFFER *buf);
	const unsigned char *NAL_BUFFER_data(const NAL_BUFFER *buf);
	unsigned int NAL_BUFFER_write(NAL_BUFFER *buf, const unsigned char *ptr,
				      unsigned int size);
	unsigned int NAL_BUFFER_read(NAL_BUFFER	*buf, unsigned char *ptr,
				     unsigned int size);
	unsigned char *NAL_BUFFER_write_ptr(NAL_BUFFER *buf);
	void NAL_BUFFER_wrote(NAL_BUFFER *buf, unsigned	int size);

DESCRIPTION
       NAL_BUFFER_new()	allocates and initialises a new	NAL_BUFFER object.

       NAL_BUFFER_free() destroys a NAL_BUFFER object.

       NAL_BUFFER_reset() will,	if necessary, cleanup any prior	state in buf
       so that it can be reused. Internally, there are various optimisations
       and benefits to using NAL_BUFFER_reset()	instead	of NAL_BUFFER_free()
       and NAL_BUFFER_new() - the implementation can try to avoid repeated re-
       allocation and reinitialisation of state.

       NAL_BUFFER_set_size() sets the size of the buffer in buf	to size	bytes.

       NAL_BUFFER_empty(), NAL_BUFFER_full(), NAL_BUFFER_notempty(), and
       NAL_BUFFER_notfull() are	functions that return a	boolean	result accord-
       ing to the size of the buffer in	buf and	how much of that buffer	is oc-
       cupied by data.

       NAL_BUFFER_used() indicates how much of buf's storage is	occupied by
       data and	NAL_BUFFER_unused() indicates how much space is	available for
       more data.

       NAL_BUFFER_size() indicates the size of buf's storage as	specified by
       the last	(successful) call to NAL_BUFFER_set_size(). This should	always
       match the total of NAL_BUFFER_used() and	NAL_BUFFER_unused().

       NAL_BUFFER_data() provides a const pointer to buf's internal storage
       for reading. This return	value is valid until buf is either destroyed
       or resized via NAL_BUFFER_set_size().

       NAL_BUFFER_write() writes into buf as much as possible of the data
       specified by ptr	and size.

       NAL_BUFFER_read() reads from buf	as much	data as	possible into the
       storage area specified by ptr and size.

       NAL_BUFFER_write_ptr() returns a	pointer	for direct write operations
       into the	internal storage of buf. This pointer must be used with	care,
       see "NOTES".

       NAL_BUFFER_wrote() allows an application	to indicate how	much data was
       directly	written	into buf following NAL_BUFFER_write_ptr(), see
       "NOTES".

RETURN VALUES
       NAL_BUFFER_new()	returns	a valid	NAL_BUFFER object on success, NULL
       otherwise.

       NAL_BUFFER_free() and NAL_BUFFER_reset()	have no	return value.

       NAL_BUFFER_empty(), NAL_BUFFER_full(), NAL_BUFFER_notempty(), and
       NAL_BUFFER_notfull() return boolean results (non-zero for true).

       NAL_BUFFER_set_size() returns non-zero for success, zero	for failure.

       NAL_BUFFER_used(), NAL_BUFFER_unused(), and NAL_BUFFER_size() return
       the number of bytes of data stored, available, or allocated (respec-
       tively) in buf.

       NAL_BUFFER_data() returns a pointer to the head of the data buffer in
       buf.

       NAL_BUFFER_write() returns the number of	bytes successfully written to
       buf.  This may be less than size	if there was less space	than that
       available for writing. NAL_BUFFER_read()	likewise returns the number of
       bytes read from buf which can be	less than size if there	was less data
       than that available for reading.

       NAL_BUFFER_write_ptr() returns a	pointer	to the first unused byte of
       the data	buffer in buf to allow writing.

       NAL_BUFFER_wrote() has no return	value.

NOTES
       The principal use of NAL_BUFFER objects is in manipulating the read and
       send buffers of a NAL_CONNECTION	object,	as returned from NAL_CONNEC-
       TION_get_read(2)	and NAL_CONNECTION_get_send(2).	This includes resizing
       these buffers directly (instead of NAL_CONNECTION_set_size(2) which
       sets both buffers jointly), reading data	from the buffer, writing data
       to the buffer, or enquiring as to the state of the buffer (empty, full,
       bytes used, space available, current size, etc).

       Use of the NAL_BUFFER_write_ptr() and NAL_BUFFER_wrote()	functions is
       not generally recommended as they directly manipulate the internals of
       a NAL_BUFFER object. The	return value of	NAL_BUFFER_write_ptr() is only
       valid for writing so long as no other operations	on buf occur before
       the subsequent call to NAL_BUFFER_wrote(), and this can create diffi-
       culties in state-machine	logic or multi-threading situations (if	ac-
       cesses to a buffer are locked, but logic	occuring between these two
       function	calls is not locked).  The NAL_BUFFER_unused() function	should
       be used to determine the	maximum	range available	to write to at the lo-
       cation returned by NAL_BUFFER_write_ptr().

SEE ALSO
       NAL_ADDRESS_new(2) - Functions for the NAL_ADDRESS type.

       NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION	type.

       NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.

       NAL_SELECTOR_new(2) - Functions for the NAL_SELECTOR type.

       distcache(8) - Overview of the distcache	architecture.

       http://www.distcache.org/ - Distcache home page.

AUTHOR
       This toolkit was	designed and implemented by Geoff Thorpe for Crypto-
       graphic Appliances Incorporated.	Since the project was released into
       open source, it has a home page and a project environment where devel-
       opment, mailing lists, and releases are organised. For problems with
       the software or this man	page please check for new releases at the
       project web-site	below, mail the	users mailing list described there, or
       contact the author at geoff@geoffthorpe.net.

       Home Page: http://www.distcache.org

1.5.1				  2004.10.19		     NAL_BUFFER_NEW(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | NOTES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=NAL_BUFFER_new&sektion=2&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help