STDIOX(3X) — Subroutines

NAME

xgets − read arbitrary length lines from a file

SYNOPSIS

#include <stdio.h>
#include <codelibs/boolean.h>
#include <codelibs/stdiox.h>
char ∗xgets(FILE ∗fp = stdin, int max = -1, boolean keepnl = FALSE);
const char ∗msprintf(const char ∗fmt, ...);
char ∗mvsprintf(char ∗&buf, size_t &buflen, const char ∗fmt, va_list ap);
CC ... -lcodelibs

DESCRIPTION

This package extends the stdio library capabilities a bit.

xgets

Xgets emulates the stdio line reading functions using dynamically allocated strings instead of fixed buffers. (It uses the stringx(3X) library to manipulate the dynamically allocated strings.) Xgets returns a line of text from file. Up to max characters are read or until a newline (or end-of-file) is seen. A value of −1 for max impiles that there is no maximum limit to the number of characters to read and xgets will return a string only when a newline (or end-of-file) is seen. The argument keepnl is either TRUE or FALSE and determines whether or not the ending newline character is appended to the returned string or not. The NULL value is returned on end-of-file.

Xgets maintains a single buffer per file which is re-used by each call. They must NOT be freed by passing them to the strfree(3X) or free(3C) functions. Use the strdup(3C) function if you need a permanent copy of the string.

msprintf

The msprintf routine prints formatted into a malloc (3X) text buffer (hence it’s name) safely without overflowing the buffer, unlike sprintf(3C). It re-uses its internal buffer on every call, so the returned string should be copied using strdup(3X) when necessary. The return value from msprintf must NOT be freed using strfree(3X) or free(3C). msprintf returns NULL if memory cannot be allocated or anything goes wrong.

mvsprintf

This routine allows more fine-control than the msprintf described above, and behaves like vsprintf (3C) except that the text buffer will never overflow. The first two arguments are references to user-defined variables buf and buflen which are used to maintain a separate safe-printing buffer. These variables should be declared static and initialized to NULL and 0 respectively before being passed to mvsprintf. These variables may also be pre-initialized to a particular buffer and size (using strnew(3X)) if desired. The buffer allocated by mvsprintf and pointed to by buf may be freed using strfree(3X) if desired.

mvsprintf takes an argument-pointer as defined in the varargs(5) or stdargs(5) packages. This allows a user-defined routine to take ... as an argument yet let mvsprintf do the real work.

mvsprintf returns NULL if memory cannot be allocated or anything else goes wrong. While it doesn’t explicitly set errno, some of the system routines that are used do, so errno may be used to detect what went seriously wrong.

CAVEATS

The underlying mvsprintf mechanism uses a single file-descriptor upon the first call, and reuses it for all subsequent calls. Calling either mvsprintf with a NULL format string will cause that file-descriptor to be closed.

msprintf calls mvsprintf to do the real work with pointers to its own static buffers. Thus msprintf and mvsprintf calls may be freely intermixed without causing problems.

Museum

Related Articles