usr.sbin/cron/bitstring.3

   1 .\" Copyright (c) 1989 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Paul Vixie.
   6 .\"
   7 .\" Redistribution and use in source and binary forms are permitted
   8 .\" provided that the above copyright notice and this paragraph are
   9 .\" duplicated in all such forms and that any documentation,
  10 .\" advertising materials, and other materials related to such
  11 .\" distribution and use acknowledge that the software was developed
  12 .\" by the University of California, Berkeley.  The name of the
  13 .\" University may not be used to endorse or promote products derived
  14 .\" from this software without specific prior written permission.
  15 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  18 .\"
  19 .\"     @(#)bitstring.3 5.1 (Berkeley) 12/13/89
  20 .\"
  21 .TH BITSTRING 3  "December 13, 1989"
  22 .UC 4
  23 .SH NAME
  24 bit_alloc, bit_clear, bit_decl, bit_ffs, bit_nclear, bit_nset,
  25 bit_set, bitstr_size, bit_test \- bit-string manipulation macros
  26 .SH SYNOPSIS
  27 .ft B
  28 .nf
  29 #include <bitstring.h>
  30
  31 name = bit_alloc(nbits)
  32 bitstr_t *name;
  33 int nbits;
  34
  35 bit_decl(name, nbits)
  36 bitstr_t name;
  37 int nbits;
  38
  39 bit_clear(name, bit)
  40 bitstr_t name;
  41 int bit;
  42
  43 bit_ffc(name, nbits, value)
  44 bitstr_t name;
  45 int nbits, *value;
  46
  47 bit_ffs(name, nbits, value)
  48 bitstr_t name;
  49 int nbits, *value;
  50
  51 bit_nclear(name, start, stop)
  52 bitstr_t name;
  53 int start, stop;
  54
  55 bit_nset(name, start, stop)
  56 bitstr_t name;
  57 int start, stop;
  58
  59 bit_set(name, bit)
  60 bitstr_t name;
  61 int bit;
  62
  63 bitstr_size(nbits)
  64 int nbits;
  65
  66 bit_test(name, bit)
  67 bitstr_t name;
  68 int bit;
  69 .fi
  70 .ft R
  71 .SH DESCRIPTION
  72 These macros operate on strings of bits.
  73 .PP
  74 .I Bit_alloc
  75 returns a pointer of type
  76 .I bitstr_t\ *
  77 to sufficient space to store
  78 .I nbits
  79 bits, or NULL if no space is available.
  80 .PP
  81 .I Bit_decl
  82 is a macro for allocating sufficient space to store
  83 .I nbits
  84 bits on the stack.
  85 .PP
  86 .I Bitstr_size
  87 returns the number of elements of type
  88 .I bitstr_t
  89 necessary to store
  90 .I nbits
  91 bits.
  92 This is useful for copying bit strings.
  93 .PP
  94 .I Bit_clear
  95 and
  96 .I bit_set
  97 clear or set the zero-based numbered bit
  98 .IR bit ,
  99 in the bit string
 100 .IR name .
 101 .PP
 102 .I Bit_nset
 103 and
 104 .I bit_nclear
 105 set or clear the zero-based numbered bits from
 106 .I start
 107 to
 108 .I stop
 109 in the bit string
 110 .IR name .
 111 .PP
 112 .I Bit_test
 113 evaluates to zero if the zero-based numbered bit
 114 .I bit
 115 of bit string
 116 .I name
 117 is set, and non-zero otherwise.
 118 .PP
 119 .I Bit_ffs
 120 sets
 121 .I *value
 122 to the zero-based number of the first bit set in the array of
 123 .I nbits
 124 bits referenced by
 125 .IR name .
 126 If no bits are set,
 127 .I *value
 128 is set to -1.
 129 .PP
 130 .I Bit_ffc
 131 sets
 132 .I *value
 133 to the zero-based number of the first bit not set in the array of
 134 .I nbits
 135 bits referenced by
 136 .IR name .
 137 If all bits are set,
 138 .I value
 139 is set to -1.
 140 .SH EXAMPLE
 141 .nf
 142 .in +5
 143 #include <limits.h>
 144 #include <bitstring.h>
 145
 146 ...
 147 #define LPR_BUSY_BIT            0
 148 #define LPR_FORMAT_BIT          1
 149 #define LPR_DOWNLOAD_BIT        2
 150 ...
 151 #define LPR_AVAILABLE_BIT       9
 152 #define LPR_MAX_BITS            10
 153
 154 make_lpr_available()
 155 {
 156         bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
 157         ...
 158         bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
 159         ...
 160         if (!bit_test(bitlist, LPR_BUSY_BIT)) {
 161                 bit_clear(bitlist, LPR_FORMAT_BIT);
 162                 bit_clear(bitlist, LPR_DOWNLOAD_BIT);
 163                 bit_set(bitlist, LPR_AVAILABLE_BIT);
 164         }
 165 }
 166 .fi
 167 .SH "SEE ALSO"
 168 malloc(3)