man/bitstring.3

   1 .\"     $NetBSD: bitstring.3,v 1.4 1994/11/30 15:24:31 jtc Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Paul Vixie.
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)bitstring.3 8.1 (Berkeley) 7/19/93
  37 .\"
  38 .Dd July 19, 1993
  39 .Dt BITSTRING 3
  40 .Os BSD 4
  41 .Sh NAME
  42 .Nm bit_alloc ,
  43 .Nm bit_clear ,
  44 .Nm bit_decl ,
  45 .Nm bit_ffs ,
  46 .Nm bit_nclear ,
  47 .Nm bit_nset,
  48 .Nm bit_set ,
  49 .Nm bitstr_size ,
  50 .Nm bit_test
  51 .Nd bit-string manipulation macros
  52 .Sh SYNOPSIS
  53 .Fd #include <bitstring.h>
  54 .Ft bitstr_t *
  55 .Fn bit_alloc "int nbits"
  56 .Fn bit_decl "bitstr_t *name" "int nbits"
  57 .Fn bit_clear "bitstr_t *name" "int bit"
  58 .Fn bit_ffc "bitstr_t *name" "int nbits" "int *value"
  59 .Fn bit_ffs "bitstr_t *name" "int nbits" "int *value"
  60 .Fn bit_nclear "bitstr_t *name" "int start" "int stop"
  61 .Fn bit_nset "bitstr_t *name" "int start" "int stop"
  62 .Fn bit_set "bitstr_t *name" "int bit"
  63 .Ft int
  64 .Fn bitstr_size "int nbits"
  65 .Ft int
  66 .Fn bit_test "bitstr_t *name" "int bit"
  67 .Sh DESCRIPTION
  68 These macros operate on strings of bits.
  69 .Pp
  70 The macro
  71 .Fn bit_alloc
  72 returns a pointer of type
  73 .Dq Fa "bitstr_t *"
  74 to sufficient space to store
  75 .Fa nbits
  76 bits, or
  77 .Dv NULL
  78 if no space is available.
  79 .Pp
  80 The macro
  81 .Fn bit_decl
  82 allocates sufficient space to store
  83 .Fa nbits
  84 bits on the stack.
  85 .Pp
  86 The macro
  87 .Fn bitstr_size
  88 returns the number of elements of type
  89 .Fa bitstr_t
  90 necessary to store
  91 .Fa nbits
  92 bits.
  93 This is useful for copying bit strings.
  94 .Pp
  95 The macros
  96 .Fn bit_clear
  97 and
  98 .Fn bit_set
  99 clear or set the zero-based numbered bit
 100 .Fa bit ,
 101 in the bit string
 102 .Ar name .
 103 .Pp
 104 The
 105 .Fn bit_nset
 106 and
 107 .Fn bit_nclear
 108 macros
 109 set or clear the zero-based numbered bits from
 110 .Fa start
 111 to
 112 .Fa stop
 113 in the bit string
 114 .Ar name .
 115 .Pp
 116 The
 117 .Fn bit_test
 118 macro
 119 evaluates to non-zero if the zero-based numbered bit
 120 .Fa bit
 121 of bit string
 122 .Fa name
 123 is set, and zero otherwise.
 124 .Pp
 125 The
 126 .Fn bit_ffs
 127 macro
 128 stores in the location referenced by
 129 .Fa value
 130 the zero-based number of the first bit set in the array of
 131 .Fa nbits
 132 bits referenced by
 133 .Fa name .
 134 If no bits are set, the location referenced by
 135 .Fa value
 136 is set to \-1.
 137 .Pp
 138 The macro
 139 .Fn bit_ffc
 140 stores in the location referenced by
 141 .Fa value
 142 the zero-based number of the first bit not set in the array of
 143 .Fa nbits
 144 bits referenced by
 145 .Fa name .
 146 If all bits are set, the location referenced by
 147 .Fa value
 148 is set to \-1.
 149 .Pp
 150 The macros
 151 .Fn bit_clear ,
 152 .Fn bit_set
 153 and
 154 .Fn bit_test
 155 will evaluate the
 156 .Fa bit
 157 argument more than once, so avoid using pre- or post-, increment or decrement.
 158 The arguments to the other macros are evaluated only once and may safely
 159 have side effects.
 160 .Sh EXAMPLE
 161 .Bd -literal -offset indent
 162 #include <limits.h>
 163 #include <bitstring.h>
 164
 165 ...
 166 #define LPR_BUSY_BIT            0
 167 #define LPR_FORMAT_BIT          1
 168 #define LPR_DOWNLOAD_BIT        2
 169 ...
 170 #define LPR_AVAILABLE_BIT       9
 171 #define LPR_MAX_BITS            10
 172
 173 make_lpr_available()
 174 {
 175         bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
 176         ...
 177         bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
 178         ...
 179         if (!bit_test(bitlist, LPR_BUSY_BIT)) {
 180                 bit_clear(bitlist, LPR_FORMAT_BIT);
 181                 bit_clear(bitlist, LPR_DOWNLOAD_BIT);
 182                 bit_set(bitlist, LPR_AVAILABLE_BIT);
 183         }
 184 }
 185 .Ed
 186 .Sh SEE ALSO
 187 .Xr malloc 3
 188 .Sh HISTORY
 189 The
 190 .Nm bitstring
 191 functions first appeared in 4.4BSD.