---
name: "stralloc"
section: "3"
platform: "linux"
package: "qmail"
version: "1.06-6.2~deb10u1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/stralloc"
---

# stralloc(3)

dynamically allocated strings

## NAME

stralloc - dynamically allocated strings

## SYNTAX

**#include \<stralloc.h\>**

int **stralloc\_ready**(&*sa*,*len*);\
 int **stralloc\_readyplus**(&*sa*,*len*);

int **stralloc\_copy**(&*sa*,&*sa2*);\
 int **stralloc\_copys**(&*sa*,*buf*);\
 int **stralloc\_copyb**(&*sa*,*buf*,*len*);

int **stralloc\_cat**(&*sa*,&*sa2*);\
 int **stralloc\_cats**(&*sa*,*buf*);\
 int **stralloc\_catb**(&*sa*,*buf*,*len*);

int **stralloc\_append**(&*sa*,*buf*);\
 int **stralloc\_0**(&*sa*);

int **stralloc\_starts**(&*sa*,*buf*);

stralloc *sa* = {0};\
 stralloc *sa2* = {0};\
 unsigned int *len*;\
 char \**buf*;

## DESCRIPTION

A **stralloc** variable holds a string in dynamically allocated space. String length is limited only by memory. String contents are unrestricted.

The **stralloc** structure has three components: *sa**.s*** is a pointer to the string, or 0 if it is not allocated; *sa**.len*** is the number of bytes in the string, if it is allocated; *sa**.a*** is the number of bytes allocated for the string, if it is allocated. A **stralloc** variable should be initialized to {0}, meaning unallocated.

**stralloc\_ready** makes sure that *sa* has enough space allocated for *len* characters. It allocates extra space if necessary.

**stralloc\_readyplus** makes sure that *sa* has enough space allocated for *len* characters more than its current length. If *sa* is unallocated, **stralloc\_readyplus** is the same as **stralloc\_ready**.

**stralloc\_copy** copies *sa2* to *sa*, allocating space if necessary. Here *sa2* is an allocated **stralloc** variable.

**stralloc\_copys** copies a 0-terminated string, *buf*, to *sa*, without the 0.

**stralloc\_copyb** copies *len* characters from *buf* to *sa*.

**stralloc\_cat** appends *sa2* to *sa*, allocating space if necessary. If *sa* is unallocated, **stralloc\_cat** is the same as **stralloc\_copy**.

**stralloc\_cats** and **stralloc\_catb** are analogous to **stralloc\_copys** and **stralloc\_copyb**.

**stralloc\_append** adds a single character, *\*buf*, to *sa*, allocating space if necessary.

**stralloc\_0** adds a single 0 character to *sa*.

**stralloc\_starts** returns 1 if the 0-terminated string *buf*, without the 0, is a prefix of *sa*.

## ERROR HANDLING

If a **stralloc** routine runs out of memory, it leaves *sa* alone and returns 0, setting **errno** appropriately. On success it returns 1; this guarantees that *sa* is allocated.

## SEE ALSO

[alloc(3)](/alloc/3.md), [error(3)](/error/3.md)