share/man/man3/bitstring.3

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Paul Vixie.
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" Copyright (c) 2014,2016 Spectra Logic Corporation
  31 .\" All rights reserved.
  32 .\"
  33 .\" Redistribution and use in source and binary forms, with or without
  34 .\" modification, are permitted provided that the following conditions
  35 .\" are met:
  36 .\" 1. Redistributions of source code must retain the above copyright
  37 .\"    notice, this list of conditions, and the following disclaimer,
  38 .\"    without modification.
  39 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  40 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  41 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  42 .\"    including a substantially similar Disclaimer requirement for further
  43 .\"    binary redistribution.
  44 .\"
  45 .\" NO WARRANTY
  46 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  47 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  48 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  49 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  50 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  51 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  52 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  53 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  54 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  55 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  56 .\" POSSIBILITY OF SUCH DAMAGES.
  57 .\"
  58 .\"     @(#)bitstring.3 8.1 (Berkeley) 7/19/93
  59 .\" $FreeBSD$
  60 .\"
  61 .Dd May 23, 2016
  62 .Dt BITSTRING 3
  63 .Os
  64 .Sh NAME
  65 .Nm bit_alloc ,
  66 .Nm bit_clear ,
  67 .Nm bit_count ,
  68 .Nm bit_decl ,
  69 .Nm bit_ffc ,
  70 .Nm bit_ffs ,
  71 .Nm bit_ffc_at ,
  72 .Nm bit_ffs_at ,
  73 .Nm bit_nclear ,
  74 .Nm bit_nset ,
  75 .Nm bit_set ,
  76 .Nm bit_test ,
  77 .Nm bitstr_size
  78 .Nd bit-string manipulation functions and macros
  79 .Sh SYNOPSIS
  80 .In bitstring.h
  81 .Ft bitstr_t *
  82 .Fn bit_alloc "int nbits"
  83 .Ft void
  84 .Fn bit_decl "bitstr_t *name" "int nbits"
  85 .Ft void
  86 .Fn bit_clear "bitstr_t *name" "int bit"
  87 .Ft void
  88 .Fn bit_count "bitstr_t *name" "int count" "int nbits" "int *value"
  89 .Ft void
  90 .Fn bit_ffc "bitstr_t *name" "int nbits" "int *value"
  91 .Ft void
  92 .Fn bit_ffs "bitstr_t *name" "int nbits" "int *value"
  93 .Ft void
  94 .Fn bit_ffc_at "bitstr_t *name" "int start" "int nbits" "int *value"
  95 .Ft void
  96 .Fn bit_ffs_at "bitstr_t *name" "int start" "int nbits" "int *value"
  97 .Ft void
  98 .Fn bit_nclear "bitstr_t *name" "int start" "int stop"
  99 .Ft void
 100 .Fn bit_nset "bitstr_t *name" "int start" "int stop"
 101 .Ft void
 102 .Fn bit_set "bitstr_t *name" "int bit"
 103 .Ft int
 104 .Fn bitstr_size "int nbits"
 105 .Ft int
 106 .Fn bit_test "bitstr_t *name" "int bit"
 107 .Sh DESCRIPTION
 108 These macros operate on strings of bits.
 109 .Pp
 110 The function
 111 .Fn bit_alloc
 112 returns a pointer of type
 113 .Dq Fa "bitstr_t *"
 114 to sufficient space to store
 115 .Fa nbits
 116 bits, or
 117 .Dv NULL
 118 if no space is available.
 119 If successful, the returned bit string is initialized with all bits cleared.
 120 .Pp
 121 The macro
 122 .Fn bit_decl
 123 declares a bit string with sufficient space to store
 124 .Fa nbits
 125 bits.
 126 .Fn bit_decl
 127 may be used to include statically sized bit strings in structure
 128 definitions or to create bit strings on the stack.
 129 Users of this macro are responsible for initialization of the bit string,
 130 typically via a global initialization of the containing struct or use of the
 131 .Fn bit_nset
 132 or
 133 .Fn bin_nclear
 134 functions.
 135 .Pp
 136 The macro
 137 .Fn bitstr_size
 138 returns the number of bytes necessary to store
 139 .Fa nbits
 140 bits.
 141 This is useful for copying bit strings.
 142 .Pp
 143 The functions
 144 .Fn bit_clear
 145 and
 146 .Fn bit_set
 147 clear or set the zero-based numbered bit
 148 .Fa bit ,
 149 in the bit string
 150 .Ar name .
 151 .Pp
 152 The
 153 .Fn bit_nset
 154 and
 155 .Fn bit_nclear
 156 functions
 157 set or clear the zero-based numbered bits from
 158 .Fa start
 159 through
 160 .Fa stop
 161 in the bit string
 162 .Ar name .
 163 .Pp
 164 The
 165 .Fn bit_test
 166 function
 167 evaluates to non-zero if the zero-based numbered bit
 168 .Fa bit
 169 of bit string
 170 .Fa name
 171 is set, and zero otherwise.
 172 .Pp
 173 The function
 174 .Fn bit_ffc
 175 stores in the location referenced by
 176 .Fa value
 177 the zero-based number of the first bit not set in the array of
 178 .Fa nbits
 179 bits referenced by
 180 .Fa name .
 181 If all bits are set, the location referenced by
 182 .Fa value
 183 is set to \-1.
 184 .Pp
 185 The
 186 .Fn bit_ffs
 187 function
 188 stores in the location referenced by
 189 .Fa value
 190 the zero-based number of the first bit set in the array of
 191 .Fa nbits
 192 bits referenced by
 193 .Fa name .
 194 If no bits are set, the location referenced by
 195 .Fa value
 196 is set to \-1.
 197 .Pp
 198 The function
 199 .Fn bit_ffc_at
 200 stores in the location referenced by
 201 .Fa value
 202 the zero-based number of the first bit not set in the array of
 203 .Fa nbits
 204 bits referenced by
 205 .Fa name ,
 206 at or after the zero-based bit index
 207 .Fa start .
 208 If all bits at or after
 209 .Fa start
 210 are set, the location referenced by
 211 .Fa value
 212 is set to \-1.
 213 .Pp
 214 The
 215 .Fn bit_ffs_at
 216 function
 217 stores in the location referenced by
 218 .Fa value
 219 the zero-based number of the first bit set in the array of
 220 .Fa nbits
 221 bits referenced by
 222 .Fa name ,
 223 at or after the zero-based bit index
 224 .Fa start .
 225 If no bits are set after
 226 .Fa start ,
 227 the location referenced by
 228 .Fa value
 229 is set to \-1.
 230 .Pp
 231 The
 232 .Fn bit_count
 233 function stores in the location referenced by
 234 .Fa value
 235 the number of bits set in the array of
 236 .Fa nbits
 237 bits referenced by
 238 .Fa name ,
 239 at or after the zero-based bit index
 240 .Fa start .
 241 .Pp
 242 The arguments in bit string macros are evaluated only once and may safely
 243 have side effects.
 244 .Sh EXAMPLES
 245 .Bd -literal -offset indent
 246 #include <limits.h>
 247 #include <bitstring.h>
 248
 249 \&...
 250 #define LPR_BUSY_BIT            0
 251 #define LPR_FORMAT_BIT          1
 252 #define LPR_DOWNLOAD_BIT        2
 253 \&...
 254 #define LPR_AVAILABLE_BIT       9
 255 #define LPR_MAX_BITS            10
 256
 257 make_lpr_available()
 258 {
 259         bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
 260         ...
 261         bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
 262         ...
 263         if (!bit_test(bitlist, LPR_BUSY_BIT)) {
 264                 bit_clear(bitlist, LPR_FORMAT_BIT);
 265                 bit_clear(bitlist, LPR_DOWNLOAD_BIT);
 266                 bit_set(bitlist, LPR_AVAILABLE_BIT);
 267         }
 268 }
 269 .Ed
 270 .Sh SEE ALSO
 271 .Xr malloc 3 ,
 272 .Xr bitset 9
 273 .Sh HISTORY
 274 The
 275 .Nm bitstring
 276 functions first appeared in
 277 .Bx 4.4 .