l4/pkg/libbsd/lib/contrib/man/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 .\" 4. 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 .\"     @(#)bitstring.3 8.1 (Berkeley) 7/19/93
  31 .\" $FreeBSD$
  32 .\"
  33 .Dd July 19, 1993
  34 .Dt BITSTRING 3
  35 .Os
  36 .Sh NAME
  37 .Nm bit_alloc ,
  38 .Nm bit_clear ,
  39 .Nm bit_decl ,
  40 .Nm bit_ffs ,
  41 .Nm bit_nclear ,
  42 .Nm bit_nset ,
  43 .Nm bit_set ,
  44 .Nm bitstr_size ,
  45 .Nm bit_test
  46 .Nd bit-string manipulation macros
  47 .Sh SYNOPSIS
  48 .In bsd/bitstring.h
  49 .Ft bitstr_t *
  50 .Fn bit_alloc "int nbits"
  51 .Ft void
  52 .Fn bit_decl "bitstr_t *name" "int nbits"
  53 .Ft void
  54 .Fn bit_clear "bitstr_t *name" "int bit"
  55 .Ft void
  56 .Fn bit_ffc "bitstr_t *name" "int nbits" "int *value"
  57 .Ft void
  58 .Fn bit_ffs "bitstr_t *name" "int nbits" "int *value"
  59 .Ft void
  60 .Fn bit_nclear "bitstr_t *name" "int start" "int stop"
  61 .Ft void
  62 .Fn bit_nset "bitstr_t *name" "int start" "int stop"
  63 .Ft void
  64 .Fn bit_set "bitstr_t *name" "int bit"
  65 .Ft int
  66 .Fn bitstr_size "int nbits"
  67 .Ft int
  68 .Fn bit_test "bitstr_t *name" "int bit"
  69 .Sh DESCRIPTION
  70 These macros operate on strings of bits.
  71 .Pp
  72 The macro
  73 .Fn bit_alloc
  74 returns a pointer of type
  75 .Dq Fa "bitstr_t *"
  76 to sufficient space to store
  77 .Fa nbits
  78 bits, or
  79 .Dv NULL
  80 if no space is available.
  81 .Pp
  82 The macro
  83 .Fn bit_decl
  84 allocates sufficient space to store
  85 .Fa nbits
  86 bits on the stack.
  87 .Pp
  88 The macro
  89 .Fn bitstr_size
  90 returns the number of elements of type
  91 .Fa bitstr_t
  92 necessary to store
  93 .Fa nbits
  94 bits.
  95 This is useful for copying bit strings.
  96 .Pp
  97 The macros
  98 .Fn bit_clear
  99 and
 100 .Fn bit_set
 101 clear or set the zero-based numbered bit
 102 .Fa bit ,
 103 in the bit string
 104 .Ar name .
 105 .Pp
 106 The
 107 .Fn bit_nset
 108 and
 109 .Fn bit_nclear
 110 macros
 111 set or clear the zero-based numbered bits from
 112 .Fa start
 113 through
 114 .Fa stop
 115 in the bit string
 116 .Ar name .
 117 .Pp
 118 The
 119 .Fn bit_test
 120 macro
 121 evaluates to non-zero if the zero-based numbered bit
 122 .Fa bit
 123 of bit string
 124 .Fa name
 125 is set, and zero otherwise.
 126 .Pp
 127 The
 128 .Fn bit_ffs
 129 macro
 130 stores in the location referenced by
 131 .Fa value
 132 the zero-based number of the first bit set in the array of
 133 .Fa nbits
 134 bits referenced by
 135 .Fa name .
 136 If no bits are set, the location referenced by
 137 .Fa value
 138 is set to \-1.
 139 .Pp
 140 The macro
 141 .Fn bit_ffc
 142 stores in the location referenced by
 143 .Fa value
 144 the zero-based number of the first bit not set in the array of
 145 .Fa nbits
 146 bits referenced by
 147 .Fa name .
 148 If all bits are set, the location referenced by
 149 .Fa value
 150 is set to \-1.
 151 .Pp
 152 The arguments to these macros are evaluated only once and may safely
 153 have side effects.
 154 .Sh EXAMPLES
 155 .Bd -literal -offset indent
 156 #include <limits.h>
 157 #include <bsd/bitstring.h>
 158
 159 \&...
 160 #define LPR_BUSY_BIT            0
 161 #define LPR_FORMAT_BIT          1
 162 #define LPR_DOWNLOAD_BIT        2
 163 \&...
 164 #define LPR_AVAILABLE_BIT       9
 165 #define LPR_MAX_BITS            10
 166
 167 make_lpr_available()
 168 {
 169         bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
 170         ...
 171         bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
 172         ...
 173         if (!bit_test(bitlist, LPR_BUSY_BIT)) {
 174                 bit_clear(bitlist, LPR_FORMAT_BIT);
 175                 bit_clear(bitlist, LPR_DOWNLOAD_BIT);
 176                 bit_set(bitlist, LPR_AVAILABLE_BIT);
 177         }
 178 }
 179 .Ed
 180 .Sh SEE ALSO
 181 .Xr malloc 3
 182 .Sh HISTORY
 183 The
 184 .Nm bitstring
 185 functions first appeared in
 186 .Bx 4.4 .