Next: bpipe_hdrf_type, Previous: bpipe_hdrf_resize, Up: Header Field Manipulations
Add a new string data field to the header.
#include <bpipe/bpipe.h>int bpipe_hdrf_string_add( BPipe *bpipe, char *name, char *data, size_t len, int copy );
BPipe *bpipe
- binary pipe to which to add the field
char *name
- the name of the field
char *data
- a pointer to the string
size_t len
- an optional length. Set to
0
to use the length of the passed stringint copy
- if true, make a copy of the data
This routine adds a character array data field to the header
associated with the passed BPipe
. Duplicate fields with the
same name are allowed; they are given different index numbers. The
new field is added to the end of the list of existing fields.
The passed name specification is duplicated.
This routine differs from bpipe_hdrf_add
in that the passed
data is expected to be a C
style null-terminated string.
It creates a one dimensional character array with an extent equal
to the length of the passed string (including the terminating null).
The calling procedure can specify an overriding string length, which
must include space for the terminating null.
If the copy
argument is true, a copy is made of the string
pointed to by the data
argument. In the case that this
string is longer than the overriding length (if provided), it is
truncated so that it will fit in the requested length and
terminated with a ‘\0’. if the copy
argument is false,
the header field will refer directly to the memory it points to.
This saves time and space for large data fields. However, if the
requested length is shorter than the actual length of the string,
it will write a ‘\0’ in the passed string at the appropriate
position.
If the passed
data pointer is NULL
, memory is allocated for it, regardless
of the state of the copy
flag.
It returns zero upon success. Upon failure it returns non-zero,
and sets bpipe_errno
.
Upon error bpipe_errno
is set to one of the following:
BPEBADARG
BPipe
has been mapped
data
was NULL
and the requested length
was less than ‘2’.
BPENOMEM
If the copy
parameter is false, the data
points to
a string and the optional length is
specified and is shorter than the actual length of the string,
bpipe_hdrf_string_add
will write a ‘\0’ into the
passed string. This may cause address violations if the
string is a const array.