NAME

string_buf_input, string_buf_output, string_buf_content, string_buf_length —

string buffer streams

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS

#include <sys/types.h>
#include <stdio.h>
#include <pdel/io/string_fp.h>

FILE *
string_buf_input(const void *buf, size_t len, int copy);

FILE *
string_buf_output(const void *mtype);

char *
string_buf_content(FILE *fp, int reset);

int
string_buf_length(FILE *fp);

DESCRIPTION

These functions allow string buffers to be read and written as streams.

string_buf_input() creates a read-only stream that reads from the buffer pointed to by buf having length len. If copy is non-zero, the contents of the buffer are copied and therefore buf doesn't need to remain valid while the stream is open. Otherwise, the data pointed to by buf is not copied and must remain valid while the stream is open. fclose(3) should be used to close the stream.

string_buf_output() creates a write-only stream that writes into an internal buffer that grows dynamically. fclose(3) should be used to close the stream; this also frees the internal buffer. The current buffer length is returned by string_buf_length().

string_buf_content() returns the contents of the internal buffer. As with string_buf_length(), the fp argument must be a stream created by string_buf_output(). If reset is zero, then the internal buffer remains valid and the returned pointer should be treated as read-only and not be freed; it also becomes invalid with the next operation on the stream. If reset is non-zero, the current buffer contents are "detached" and returned by string_buf_content(), and a new, empty internal buffer is created; in this case, the caller is responsible for eventually freeing the returned buffer, which is allocated with typed_mem(3) type mtype, and its contents remain valid until then.

In either case, the data returned by string_buf_content() is guaranteed to have one additional '\0' byte appended. Therefore, it is always safe to treat this pointer as a normal C string. However, any '\0' bytes previously written to the stream will cause this string to appear truncated.

RETURN VALUES

string_buf_input(), string_buf_output(), and string_buf_content() return NULL to indicate an error, with errno set appropriately.

Even if string_buf_content() returns NULL, the stream will still need to be closed.

IMPLEMENTATION NOTES

string_buf_content() and string_buf_length() attempt to verify that the supplied stream was indeed created by string_buf_output(). If they detect otherwise, an immediate assertion failure is generated.

HISTORY

The PDEL library was developed at Packet Design, LLC. http://www.packetdesign.com/

AUTHORS

Archie Cobbs ⟨archie@freebsd.org⟩