1.\" Copyright (c) 1989, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Paul Vixie. 6.\" %sccs.include.redist.man% 7.\" 8.\" @(#)bitstring.3 5.5 (Berkeley) 06/09/93 9.\" 10.Dd 11.Dt BITSTRING 3 12.Os BSD 4 13.Sh NAME 14.Nm bit_alloc , 15.Nm bit_clear , 16.Nm bit_decl , 17.Nm bit_ffs , 18.Nm bit_nclear , 19.Nm bit_nset, 20.Nm bit_set , 21.Nm bitstr_size , 22.Nm bit_test 23.Nd bit-string manipulation macros 24.Sh SYNOPSIS 25.Fd #include <bitstring.h> 26.Ft bitstr_t * 27.Fn bit_alloc "int nbits" 28.Fn bit_decl "bit_str name" "int nbits" 29.Fn bit_clear "bit_str name" "int bit" 30.Fn bit_ffc "bit_str name" "int nbits" "int *value" 31.Fn bit_ffs "bit_str name" "int nbits" "int *value" 32.Fn bit_nclear "bit_str name" "int start" "int stop" 33.Fn bit_nset "bit_str name" "int start" "int stop" 34.Fn bit_set "bit_str name" "int bit" 35.Fn bitstr_size "int nbits" 36.Fn bit_test "bit_str name" "int bit" 37.Sh DESCRIPTION 38These macros operate on strings of bits. 39.Pp 40The macro 41.Fn bit_alloc 42returns a pointer of type 43.Dq Fa "bitstr_t *" 44to sufficient space to store 45.Fa nbits 46bits, or 47.Dv NULL 48if no space is available. 49.Pp 50The macro 51.Fn bit_decl 52allocates sufficient space to store 53.Fa nbits 54bits on the stack. 55.Pp 56The macro 57.Fn bitstr_size 58returns the number of elements of type 59.Fa bitstr_t 60necessary to store 61.Fa nbits 62bits. 63This is useful for copying bit strings. 64.Pp 65The macros 66.Fn bit_clear 67and 68.Fn bit_set 69clear or set the zero-based numbered bit 70.Fa bit , 71in the bit string 72.Ar name . 73.Pp 74The 75.Fn bit_nset 76and 77.Fn bit_nclear 78macros 79set or clear the zero-based numbered bits from 80.Fa start 81to 82.Fa stop 83in the bit string 84.Ar name . 85.Pp 86The 87.Fn bit_test 88macro 89evaluates to zero if the zero-based numbered bit 90.Fa bit 91of bit string 92.Fa name 93is set, and non-zero otherwise. 94.Pp 95The 96.Fn bit_ffs 97macro 98stores in the location referenced by 99.Fa value 100the zero-based number of the first bit set in the array of 101.Fa nbits 102bits referenced by 103.Fa name . 104If no bits are set, the location referenced by 105.Fa value 106is set to \-1. 107.Pp 108The macro 109.Fn bit_ffc 110stores in the location referenced by 111.Fa value 112the zero-based number of the first bit not set in the array of 113.Fa nbits 114bits referenced by 115.Fa name . 116If all bits are set, the location referenced by 117.Fa value 118is set to \-1. 119.Pp 120The arguments to these macros are evaluated only once and may safely 121have side effects. 122.Sh EXAMPLE 123.Bd -literal -offset indent 124#include <limits.h> 125#include <bitstring.h> 126 127... 128#define LPR_BUSY_BIT 0 129#define LPR_FORMAT_BIT 1 130#define LPR_DOWNLOAD_BIT 2 131... 132#define LPR_AVAILABLE_BIT 9 133#define LPR_MAX_BITS 10 134 135make_lpr_available() 136{ 137 bitstr_t bit_decl(bitlist, LPR_MAX_BITS); 138 ... 139 bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); 140 ... 141 if (!bit_test(bitlist, LPR_BUSY_BIT)) { 142 bit_clear(bitlist, LPR_FORMAT_BIT); 143 bit_clear(bitlist, LPR_DOWNLOAD_BIT); 144 bit_set(bitlist, LPR_AVAILABLE_BIT); 145 } 146} 147.Ed 148.Sh SEE ALSO 149.Xr malloc 3 150.Sh HISTORY 151The 152.Nm bitstring 153functions first appeared in 4.4BSD. 154