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