---
name: "bitstring"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/bitstring"
---

# bitstring(3)

bit-string manipulation macros

## NAME

**bit\_alloc**, **bit\_clear**, **bit\_decl**, **bit\_ffs**, **bit\_nclear**, **bit\_nset,** **bit\_set**, **bitstr\_size**, **bit\_test** – bit-string manipulation macros

## SYNOPSIS

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

*bitstr\_t* *\**\

**bit\_alloc**(*int nbits*);

**bit\_decl**(*bitstr\_t \*name*, *int nbits*);

**bit\_clear**(*bitstr\_t \*name*, *int bit*);

**bit\_ffc**(*bitstr\_t \*name*, *int nbits*, *int \*value*);

**bit\_ffs**(*bitstr\_t \*name*, *int nbits*, *int \*value*);

**bit\_nclear**(*bitstr\_t \*name*, *int start*, *int stop*);

**bit\_nset**(*bitstr\_t \*name*, *int start*, *int stop*);

**bit\_set**(*bitstr\_t \*name*, *int bit*);

*int*\

**bitstr\_size**(*int nbits*);

*int*\

**bit\_test**(*bitstr\_t \*name*, *int bit*);

## DESCRIPTION

These macros operate on strings of bits.

The macro **bit\_alloc**() returns a pointer of type “*bitstr\_t \**” to sufficient space to store *nbits* bits, or NULL if no space is available.

The macro **bit\_decl**() allocates sufficient space to store *nbits* bits on the stack.

The macro **bitstr\_size**() returns the number of elements of type *bitstr\_t* necessary to store *nbits* bits. This is useful for copying bit strings.

The macros **bit\_clear**() and **bit\_set**() clear or set the zero-based numbered bit *bit*, in the bit string *name*.

The **bit\_nset**() and **bit\_nclear**() macros set or clear the zero-based numbered bits from *start* to *stop* in the bit string *name*.

The **bit\_test**() macro evaluates to non-zero if the zero-based numbered bit *bit* of bit string *name* is set, and zero otherwise.

The **bit\_ffs**() macro stores in the location referenced by *value* the zero-based number of the first bit set in the array of *nbits* bits referenced by *name*. If no bits are set, the location referenced by *value* is set to -1.

The macro **bit\_ffc**() stores in the location referenced by *value* the zero-based number of the first bit not set in the array of *nbits* bits referenced by *name*. If all bits are set, the location referenced by *value* is set to -1.

The macros **bit\_clear**(), **bit\_set**() and **bit\_test**() will evaluate the *bit* argument more than once, so avoid using pre- or post-, increment or decrement. The arguments to the other macros are evaluated only once and may safely have side effects.

## EXAMPLE

```
#include <limits.h>
#include <bitstring.h>
...
#define	LPR_BUSY_BIT		0
#define	LPR_FORMAT_BIT		1
#define	LPR_DOWNLOAD_BIT	2
...
#define	LPR_AVAILABLE_BIT	9
#define	LPR_MAX_BITS		10
make_lpr_available()
{
	bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
	...
	bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
	...
	if (!bit_test(bitlist, LPR_BUSY_BIT)) {
		bit_clear(bitlist, LPR_FORMAT_BIT);
		bit_clear(bitlist, LPR_DOWNLOAD_BIT);
		bit_set(bitlist, LPR_AVAILABLE_BIT);
	}
}
```

## SEE ALSO

[malloc(3)](/malloc/3.md)

## HISTORY

The **bitstring** functions first appeared in 4.4BSD.