Next: , Previous: bpipe_hdrf_resize, Up: Header Field Manipulations


A.2.9 bpipe_hdrf_string_add

Add a new string data field to the header.

Synopsis

     #include <bpipe/bpipe.h>
     
     
     
int bpipe_hdrf_string_add( BPipe *bpipe, char *name, char *data, size_t len, int copy );

Parameters

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 string
int copy
if true, make a copy of the data

Description

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.

Returns

It returns zero upon success. Upon failure it returns non-zero, and sets bpipe_errno.

Errors

Upon error bpipe_errno is set to one of the following:

BPEBADARG

BPENOMEM
a memory allocation failed

Warnings

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.