---
name: "strbuf"
section: "3"
platform: "linux"
package: "libxgks-dev"
version: "2.6.1+dfsg.2-17"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/strbuf"
---

# strbuf(3)

Unidata string-buffer

## NAME

strbuf, sbnew, sbcpy, sbncpy, sbcat, sbncat, sbstr, sblen, sbmax, sbgrow, sbfree - Unidata string-buffer

## SYNOPSIS

```
#include "udposix.h"
#include <stddef.h>	/* for "size_t" */
#include "strbuf.h"

Strbuf	*sbnew(size_t max)
Strbuf	*sbensure(Strbuf *sb, size_t max)
Strbuf	*sbcpy(Strbuf *sb, const char *string)
Strbuf	*sbncpy(Strbuf *sb, const char *string, size_t len)
Strbuf	*sbcat(Strbuf *sb, const char *string)
Strbuf	*sbncat(Strbuf *sb, const char *string, size_t len)
char	*sbstr(const Strbuf *sb)
size_t	sblen(const Strbuf *sb)
size_t	sbmax(const Strbuf *sb)
Strbuf	*sbgrow(Strbuf *sb)
Strbuf	*sbfree(Strbuf *sb)
```

## DESCRIPTION

These routines define the Unidata string-buffer abstraction.  This abstraction permits operating on strings without concern for size (e.g. arbitrary concatenation).

**sbnew()** creates a new instance of a string buffer. *max* is the initial maximum size of the string buffer, which is the number of characters the buffer may hold, excluding the terminating **´\\0´** character.  Although the buffer will grow beyond this size if necessary, it is in the user's interest to set *max* to an appropriate value (e.g.  sufficient to hold 90% of it's potential population). This function returns the new string-buffer or NULL if an error occurs.

**sbensure()** ensure that the string buffer will be able to contain a string having *max* characters (excluding the terminating **´\\0´**). This function returns the new string-buffer or NULL if an error occurs.

**sbcpy()** sets the string-buffer to *string*, which must be 0-terminated. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is  unchanged.

**sbncpy()** sets the string-buffer to *string*. *len* is the number of characters in *string* to use and should  exclude any terminating **\\'0´** character. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is  unchanged.

**sbcat()** appends *string*, which must be 0-terminated, to the contents of the  string-buffer. If the string-buffer has not been set via an earlier call to **sbcpy()** or **sbncpy()**, then the result is the same as  **sbcpy(***sb***,** *string***)**. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is  unchanged.

**sbncat()** appends *string* to the contents of the string-buffer. *len* is the number of characters to append and should exclude any  terminating **\\'0´** character. If the string-buffer has not been set via an earlier call to **sbcpy()** or **sbncpy()**, then the result is the same as  **sbcpy(***sb***,** *string***)**. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is  unchanged.

**sbstr()** returns a pointer to the **´\\0´**-terminated string in the  string-buffer. If the string buffer has not been set, then  the pointed-to string is empty (NB: the pointer is not NULL). The returned string pointer may be used like any other string pointer provided the user has ensured the size of the string-buffer via a call to **sbensure()**, if appropriate.  For example:

```
(void) sbensure(sb, strlen(string));
(void) strcpy(sbstr(sb), string);
```

When string buffers are used this way, the calling application is responsible for ensuring proper **´\\0´**-termination.

**sblen()** returns the number of characters in the string-buffer, excluding the terminating **´\\0´** character. If the string-buffer has not been set, then the returned length is zero.

**sbmax()** returns the maximum number of characters that the string-buffer can currently hold, excluding the terminating **´\\0´** character.

**sbgrow()** increases the size of the string buffer. This is useful when there is no a priori knowledge of how large the string buffer should be.

**sbfree()** releases the resources used by the string-buffer back to the operating-system and should be called when the string-buffer is no longer needed. It always returns **(Strbuf\*)NULL**.

This package uses the UDPOSIX programming environment and the udalloc(3) memory allocation package.

## MAINTAINER

Steve Emmerson \<steve@unidata.ucar.edu\>.

## SEE ALSO

**udalloc**(3), **udposix**(3).