usr.bin/jot/jot.1

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)jot.1       8.1 (Berkeley) 6/6/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 2, 2010
  32 .Dt JOT 1
  33 .Os
  34 .Sh NAME
  35 .Nm jot
  36 .Nd print sequential or random data
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl cnr
  40 .Op Fl b Ar word
  41 .Op Fl w Ar word
  42 .Op Fl s Ar string
  43 .Op Fl p Ar precision
  44 .Op Ar reps Op Ar begin Op Ar end Op Ar s
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility is used to print out increasing, decreasing, random,
  49 or redundant data, usually numbers, one per line.
  50 .Pp
  51 The following options are available:
  52 .Bl -tag -width indent
  53 .It Fl r
  54 Generate random data instead of the default sequential data.
  55 .It Fl b Ar word
  56 Just print
  57 .Ar word
  58 repetitively.
  59 .It Fl w Ar word
  60 Print
  61 .Ar word
  62 with the generated data appended to it.
  63 Octal, hexadecimal, exponential,
  64 .Tn ASCII ,
  65 zero padded,
  66 and right-adjusted representations
  67 are possible by using the appropriate
  68 .Xr printf 3
  69 conversion specification inside
  70 .Ar word ,
  71 in which case the data are inserted rather than appended.
  72 .It Fl c
  73 This is an abbreviation for
  74 .Fl w Ar %c .
  75 .It Fl s Ar string
  76 Print data separated by
  77 .Ar string .
  78 Normally, newlines separate data.
  79 .It Fl n
  80 Do not print the final newline normally appended to the output.
  81 .It Fl p Ar precision
  82 Print only as many digits or characters of the data
  83 as indicated by the integer
  84 .Ar precision .
  85 In the absence of
  86 .Fl p ,
  87 the precision is the greater of the precisions of
  88 .Ar begin
  89 and
  90 .Ar end .
  91 The
  92 .Fl p
  93 option is overridden by whatever appears in a
  94 .Xr printf 3
  95 conversion following
  96 .Fl w .
  97 .El
  98 .Pp
  99 The last four arguments indicate, respectively,
 100 the number of data, the lower bound, the upper bound,
 101 and the step size or, for random data, the seed.
 102 While at least one of them must appear,
 103 any of the other three may be omitted, and
 104 will be considered as such if given as
 105 .Fl ""
 106 or as an empty string.
 107 Any three of these arguments determines the fourth.
 108 If four are specified and the given and computed values of
 109 .Ar reps
 110 conflict, the lower value is used.
 111 If fewer than three are specified, defaults are assigned
 112 left to right, except for
 113 .Ar s ,
 114 which assumes a default of 1 or -1 if both
 115 .Ar begin
 116 and
 117 .Ar end
 118 are given.
 119 .Pp
 120 Defaults for the four arguments are, respectively,
 121 100, 1, 100, and 1, except that when random data are requested,
 122 the seed,
 123 .Ar s ,
 124 is picked randomly.
 125 The
 126 .Ar reps
 127 argument is expected to be an unsigned integer,
 128 and if given as zero is taken to be infinite.
 129 The
 130 .Ar begin
 131 and
 132 .Ar end
 133 arguments may be given as real numbers or as characters
 134 representing the corresponding value in
 135 .Tn ASCII .
 136 The last argument must be a real number.
 137 .Pp
 138 Random numbers are obtained through
 139 .Xr arc4random 3
 140 when no seed is specified,
 141 and through
 142 .Xr random 3
 143 when a seed is given.
 144 When
 145 .Nm
 146 is asked to generate random integers or characters with begin
 147 and end values in the range of the random number generator function
 148 and no format is specified with one of the
 149 .Fl w ,
 150 .Fl b ,
 151 or
 152 .Fl p
 153 options,
 154 .Nm
 155 will arrange for all the values in the range to appear in the output
 156 with an equal probability.
 157 In all other cases be careful to ensure that the output format's
 158 rounding or truncation will not skew the distribution of output
 159 values in an unintended way.
 160 .Pp
 161 The name
 162 .Nm
 163 derives in part from
 164 .Nm iota ,
 165 a function in APL.
 166 .Ss Rounding and truncation
 167 The
 168 .Nm
 169 utility uses double precision floating point arithmetic internally.
 170 Before printing a number, it is converted depending on the output
 171 format used.
 172 .Pp
 173 If no output format is specified or the output format is a
 174 floating point format
 175 .Po
 176 .Sq E ,
 177 .Sq G ,
 178 .Sq e ,
 179 .Sq f ,
 180 or
 181 .Sq g
 182 .Pc ,
 183 the value is rounded using the
 184 .Xr printf 3
 185 function, taking into account the requested precision.
 186 .Pp
 187 If the output format is an integer format
 188 .Po
 189 .Sq D ,
 190 .Sq O ,
 191 .Sq U ,
 192 .Sq X ,
 193 .Sq c ,
 194 .Sq d ,
 195 .Sq i ,
 196 .Sq o ,
 197 .Sq u ,
 198 or
 199 .Sq x
 200 .Pc ,
 201 the value is converted to an integer value by truncation.
 202 .Pp
 203 As an illustration, consider the following command:
 204 .Bd -literal -offset indent
 205 $ jot 6 1 10 0.5
 206 1
 207 2
 208 2
 209 2
 210 3
 211 4
 212 .Ed
 213 .Pp
 214 By requesting an explicit precision of 1, the values generated before rounding
 215 can be seen.
 216 The .5 values are rounded down if the integer part is even,
 217 up otherwise.
 218 .Bd -literal -offset indent
 219 $ jot -p 1 6 1 10 0.5
 220 1.0
 221 1.5
 222 2.0
 223 2.5
 224 3.0
 225 3.5
 226 .Ed
 227 .Pp
 228 By offsetting the values slightly, the values generated by the following
 229 command are always rounded down:
 230 .Bd -literal -offset indent
 231 $ jot -p 0 6 .9999999999 10 0.5
 232 1
 233 1
 234 2
 235 2
 236 3
 237 3
 238 .Ed
 239 .Pp
 240 Another way of achieving the same result is to force truncation by
 241 specifying an integer format:
 242 .Bd -literal -offset indent
 243 $ jot -w %d 6 1 10 0.5
 244 .Ed
 245 .Sh EXIT STATUS
 246 .Ex -std
 247 .Sh EXAMPLES
 248 The command
 249 .Dl jot - 1 10
 250 .Pp
 251 prints the integers from 1 to 10,
 252 while the command
 253 .Dl jot 21 -1 1.00
 254 .Pp
 255 prints 21 evenly spaced numbers increasing from -1 to 1.
 256 The
 257 .Tn ASCII
 258 character set is generated with
 259 .Dl jot -c 128 0
 260 .Pp
 261 and the strings xaa through xaz with
 262 .Dl jot -w xa%c 26 a
 263 .Pp
 264 while 20 random 8-letter strings are produced with
 265 .Dl "jot -r -c 160 a z | rs -g 0 8"
 266 .Pp
 267 Infinitely many
 268 .Em yes Ns 's
 269 may be obtained through
 270 .Dl jot -b yes 0
 271 .Pp
 272 and thirty
 273 .Xr ed 1
 274 substitution commands applying to lines 2, 7, 12, etc.\& is
 275 the result of
 276 .Dl jot -w %ds/old/new/ 30 2 - 5
 277 .Pp
 278 The stuttering sequence 9, 9, 8, 8, 7, etc.\& can be
 279 produced by truncating the output precision and a suitable choice of step size,
 280 as in
 281 .Dl jot -w %d - 9.5 0 -.5
 282 .Pp
 283 and a file containing exactly 1024 bytes is created with
 284 .Dl jot -b x 512 > block
 285 .Pp
 286 Finally, to set tabs four spaces apart starting
 287 from column 10 and ending in column 132, use
 288 .Dl expand -`jot -s, - 10 132 4`
 289 .Pp
 290 and to print all lines 80 characters or longer,
 291 .Dl grep `jot -s \&"\&" -b \&. 80`
 292 .Sh DIAGNOSTICS
 293 The following diagnostic messages deserve special explanation:
 294 .Bl -diag
 295 .It "illegal or unsupported format '%s'"
 296 The requested conversion format specifier for
 297 .Xr printf 3
 298 was not of the form
 299 .Dl %[#][ ][{+,-}][0-9]*[.[0-9]*]?
 300 where
 301 .Dq ?\&
 302 must be one of
 303 .Dl [l]{d,i,o,u,x}
 304 or
 305 .Dl {c,e,f,g,D,E,G,O,U,X}
 306 .It "range error in conversion"
 307 A value to be printed fell outside the range of the data type
 308 associated with the requested output format.
 309 .It "too many conversions"
 310 More than one conversion format specifier has been supplied,
 311 but only one is allowed.
 312 .El
 313 .Sh SEE ALSO
 314 .Xr ed 1 ,
 315 .Xr expand 1 ,
 316 .Xr rs 1 ,
 317 .Xr seq 1 ,
 318 .Xr yes 1 ,
 319 .Xr arc4random 3 ,
 320 .Xr printf 3 ,
 321 .Xr random 3
 322 .Sh HISTORY
 323 The
 324 .Nm
 325 utility first appeared in
 326 .Bx 4.2 .