NAL_BUFFER_new(2)

1NAL_BUFFER_NEW(2)                  distcache                 NAL_BUFFER_NEW(2)
2
3
4

NAME

6       NAL_BUFFER_new, NAL_BUFFER_free, NAL_BUFFER_set_size, NAL_BUFFER_empty,
7       NAL_BUFFER_full, NAL_BUFFER_notempty, NAL_BUFFER_notfull, NAL_BUF‐
8       FER_used, NAL_BUFFER_unused, NAL_BUFFER_data, NAL_BUFFER_size, NAL_BUF‐
9       FER_write, NAL_BUFFER_read, NAL_BUFFER_write_ptr, NAL_BUFFER_takedata,
10       NAL_BUFFER_wrote - libnal buffer functions
11

SYNOPSIS

13        #include <libnal/nal.h>
14
15        NAL_BUFFER *NAL_BUFFER_new(void);
16        void NAL_BUFFER_free(NAL_BUFFER *buf);
17        void NAL_BUFFER_reset(NAL_BUFFER *buf);
18        int NAL_BUFFER_set_size(NAL_BUFFER *buf, unsigned int size);
19        int NAL_BUFFER_empty(const NAL_BUFFER *buf);
20        int NAL_BUFFER_full(const NAL_BUFFER *buf);
21        int NAL_BUFFER_notempty(const NAL_BUFFER *buf);
22        int NAL_BUFFER_notfull(const NAL_BUFFER *buf);
23        unsigned int NAL_BUFFER_used(const NAL_BUFFER *buf);
24        unsigned int NAL_BUFFER_unused(const NAL_BUFFER *buf);
25        unsigned int NAL_BUFFER_size(const NAL_BUFFER *buf);
26        const unsigned char *NAL_BUFFER_data(const NAL_BUFFER *buf);
27        unsigned int NAL_BUFFER_write(NAL_BUFFER *buf, const unsigned char *ptr,
28                                      unsigned int size);
29        unsigned int NAL_BUFFER_read(NAL_BUFFER *buf, unsigned char *ptr,
30                                     unsigned int size);
31        unsigned char *NAL_BUFFER_write_ptr(NAL_BUFFER *buf);
32        void NAL_BUFFER_wrote(NAL_BUFFER *buf, unsigned int size);
33

DESCRIPTION

35       NAL_BUFFER_new() allocates and initialises a new NAL_BUFFER object.
36
37       NAL_BUFFER_free() destroys a NAL_BUFFER object.
38
39       NAL_BUFFER_reset() will, if necessary, cleanup any prior state in buf
40       so that it can be reused. Internally, there are various optimisations
41       and benefits to using NAL_BUFFER_reset() instead of NAL_BUFFER_free()
42       and NAL_BUFFER_new() - the implementation can try to avoid repeated
43       reallocation and reinitialisation of state.
44
45       NAL_BUFFER_set_size() sets the size of the buffer in buf to size bytes.
46
47       NAL_BUFFER_empty(), NAL_BUFFER_full(), NAL_BUFFER_notempty(), and
48       NAL_BUFFER_notfull() are functions that return a boolean result accord‐
49       ing to the size of the buffer in buf and how much of that buffer is
50       occupied by data.
51
52       NAL_BUFFER_used() indicates how much of buf's storage is occupied by
53       data and NAL_BUFFER_unused() indicates how much space is available for
54       more data.
55
56       NAL_BUFFER_size() indicates the size of buf's storage as specified by
57       the last (successful) call to NAL_BUFFER_set_size(). This should always
58       match the total of NAL_BUFFER_used() and NAL_BUFFER_unused().
59
60       NAL_BUFFER_data() provides a const pointer to buf's internal storage
61       for reading. This return value is valid until buf is either destroyed
62       or resized via NAL_BUFFER_set_size().
63
64       NAL_BUFFER_write() writes into buf as much as possible of the data
65       specified by ptr and size.
66
67       NAL_BUFFER_read() reads from buf as much data as possible into the
68       storage area specified by ptr and size.
69
70       NAL_BUFFER_write_ptr() returns a pointer for direct write operations
71       into the internal storage of buf. This pointer must be used with care,
72       see "NOTES".
73
74       NAL_BUFFER_wrote() allows an application to indicate how much data was
75       directly written into buf following NAL_BUFFER_write_ptr(), see
76       "NOTES".
77

RETURN VALUES

79       NAL_BUFFER_new() returns a valid NAL_BUFFER object on success, NULL
80       otherwise.
81
82       NAL_BUFFER_free() and NAL_BUFFER_reset() have no return value.
83
84       NAL_BUFFER_empty(), NAL_BUFFER_full(), NAL_BUFFER_notempty(), and
85       NAL_BUFFER_notfull() return boolean results (non-zero for true).
86
87       NAL_BUFFER_set_size() returns non-zero for success, zero for failure.
88
89       NAL_BUFFER_used(), NAL_BUFFER_unused(), and NAL_BUFFER_size() return
90       the number of bytes of data stored, available, or allocated (respec‐
91       tively) in buf.
92
93       NAL_BUFFER_data() returns a pointer to the head of the data buffer in
94       buf.
95
96       NAL_BUFFER_write() returns the number of bytes successfully written to
97       buf.  This may be less than size if there was less space than that
98       available for writing. NAL_BUFFER_read() likewise returns the number of
99       bytes read from buf which can be less than size if there was less data
100       than that available for reading.
101
102       NAL_BUFFER_write_ptr() returns a pointer to the first unused byte of
103       the data buffer in buf to allow writing.
104
105       NAL_BUFFER_wrote() has no return value.
106

NOTES

108       The principal use of NAL_BUFFER objects is in manipulating the read and
109       send buffers of a NAL_CONNECTION object, as returned from NAL_CONNEC‐
110       TION_get_read(2) and NAL_CONNECTION_get_send(2). This includes resizing
111       these buffers directly (instead of NAL_CONNECTION_set_size(2) which
112       sets both buffers jointly), reading data from the buffer, writing data
113       to the buffer, or enquiring as to the state of the buffer (empty, full,
114       bytes used, space available, current size, etc).
115
116       Use of the NAL_BUFFER_write_ptr() and NAL_BUFFER_wrote() functions is
117       not generally recommended as they directly manipulate the internals of
118       a NAL_BUFFER object. The return value of NAL_BUFFER_write_ptr() is only
119       valid for writing so long as no other operations on buf occur before
120       the subsequent call to NAL_BUFFER_wrote(), and this can create diffi‐
121       culties in state-machine logic or multi-threading situations (if
122       accesses to a buffer are locked, but logic occuring between these two
123       function calls is not locked).  The NAL_BUFFER_unused() function should
124       be used to determine the maximum range available to write to at the
125       location returned by NAL_BUFFER_write_ptr().
126

AUTHOR

141       This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
142       graphic Appliances Incorporated. Since the project was released into
143       open source, it has a home page and a project environment where devel‐
144       opment, mailing lists, and releases are organised. For problems with
145       the software or this man page please check for new releases at the
146       project web-site below, mail the users mailing list described there, or
147       contact the author at geoff@geoffthorpe.net.
148
149       Home Page: http://www.distcache.org
150
151
152
1531.4.5                             2004.03.23                 NAL_BUFFER_NEW(2)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

NOTES

SEE ALSO

AUTHOR