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