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