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 .\" 3. 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 September 21, 2019
  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 one or two are specified, defaults are assigned
 112 starting with
 113 .Ar s ,
 114 which assumes a default of 1 (or -1 if
 115 .Ar begin
 116 and
 117 .Ar end
 118 specify a descending range).
 119 Then the default values are assigned to the leftmost omitted arguments until
 120 three arguments are set.
 121 .Pp
 122 Defaults for the four arguments are, respectively,
 123 100, 1, 100, and 1, except that when random data are requested,
 124 the seed,
 125 .Ar s ,
 126 is picked randomly.
 127 The
 128 .Ar reps
 129 argument is expected to be an unsigned integer,
 130 and if given as zero is taken to be infinite.
 131 The
 132 .Ar begin
 133 and
 134 .Ar end
 135 arguments may be given as real numbers or as characters
 136 representing the corresponding value in
 137 .Tn ASCII .
 138 The last argument must be a real number.
 139 .Pp
 140 Random numbers are obtained through
 141 .Xr arc4random 3
 142 when no seed is specified,
 143 and through
 144 .Xr random 3
 145 when a seed is given.
 146 When
 147 .Nm
 148 is asked to generate random integers or characters with begin
 149 and end values in the range of the random number generator function
 150 and no format is specified with one of the
 151 .Fl w ,
 152 .Fl b ,
 153 or
 154 .Fl p
 155 options,
 156 .Nm
 157 will arrange for all the values in the range to appear in the output
 158 with an equal probability.
 159 In all other cases be careful to ensure that the output format's
 160 rounding or truncation will not skew the distribution of output
 161 values in an unintended way.
 162 .Pp
 163 The name
 164 .Nm
 165 derives in part from
 166 .Nm iota ,
 167 a function in APL.
 168 .Ss Rounding and truncation
 169 The
 170 .Nm
 171 utility uses double precision floating point arithmetic internally.
 172 Before printing a number, it is converted depending on the output
 173 format used.
 174 .Pp
 175 If no output format is specified or the output format is a
 176 floating point format
 177 .Po
 178 .Sq E ,
 179 .Sq G ,
 180 .Sq e ,
 181 .Sq f ,
 182 or
 183 .Sq g
 184 .Pc ,
 185 the value is rounded using the
 186 .Xr printf 3
 187 function, taking into account the requested precision.
 188 .Pp
 189 If the output format is an integer format
 190 .Po
 191 .Sq D ,
 192 .Sq O ,
 193 .Sq U ,
 194 .Sq X ,
 195 .Sq c ,
 196 .Sq d ,
 197 .Sq i ,
 198 .Sq o ,
 199 .Sq u ,
 200 or
 201 .Sq x
 202 .Pc ,
 203 the value is converted to an integer value by truncation.
 204 .Pp
 205 As an illustration, consider the following command:
 206 .Bd -literal -offset indent
 207 $ jot 6 1 10 0.5
 208 1
 209 2
 210 2
 211 2
 212 3
 213 4
 214 .Ed
 215 .Pp
 216 By requesting an explicit precision of 1, the values generated before rounding
 217 can be seen.
 218 The .5 values are rounded down if the integer part is even,
 219 up otherwise.
 220 .Bd -literal -offset indent
 221 $ jot -p 1 6 1 10 0.5
 222 1.0
 223 1.5
 224 2.0
 225 2.5
 226 3.0
 227 3.5
 228 .Ed
 229 .Pp
 230 By offsetting the values slightly, the values generated by the following
 231 command are always rounded down:
 232 .Bd -literal -offset indent
 233 $ jot -p 0 6 .9999999999 10 0.5
 234 1
 235 1
 236 2
 237 2
 238 3
 239 3
 240 .Ed
 241 .Pp
 242 Another way of achieving the same result is to force truncation by
 243 specifying an integer format:
 244 .Bd -literal -offset indent
 245 $ jot -w %d 6 1 10 0.5
 246 .Ed
 247 .Sh EXIT STATUS
 248 .Ex -std
 249 .Sh EXAMPLES
 250 The command
 251 .Dl jot - 1 10
 252 .Pp
 253 prints the integers from 1 to 10,
 254 while the command
 255 .Dl jot 21 -1 1.00
 256 .Pp
 257 prints 21 evenly spaced numbers increasing from -1 to 1.
 258 The
 259 .Tn ASCII
 260 character set is generated with
 261 .Dl jot -c 128 0
 262 .Pp
 263 and the strings xaa through xaz with
 264 .Dl jot -w xa%c 26 a
 265 .Pp
 266 while 20 random 8-letter strings are produced with
 267 .Dl "jot -r -c 160 a z | rs -g 0 8"
 268 .Pp
 269 Infinitely many
 270 .Em yes Ns 's
 271 may be obtained through
 272 .Dl jot -b yes 0
 273 .Pp
 274 and thirty
 275 .Xr ed 1
 276 substitution commands applying to lines 2, 7, 12, etc.\& is
 277 the result of
 278 .Dl jot -w %ds/old/new/ 30 2 - 5
 279 .Pp
 280 The stuttering sequence 9, 9, 8, 8, 7, etc.\& can be
 281 produced by truncating the output precision and a suitable choice of step size,
 282 as in
 283 .Dl jot -w %d - 9.5 0 -.5
 284 .Pp
 285 and a file containing exactly 1024 bytes is created with
 286 .Dl jot -b x 512 > block
 287 .Pp
 288 Finally, to set tabs four spaces apart starting
 289 from column 10 and ending in column 132, use
 290 .Dl expand -`jot -s, - 10 132 4`
 291 .Pp
 292 and to print all lines 80 characters or longer,
 293 .Dl grep `jot -s \&"\&" -b \&. 80`
 294 .Sh DIAGNOSTICS
 295 The following diagnostic messages deserve special explanation:
 296 .Bl -diag
 297 .It "illegal or unsupported format '%s'"
 298 The requested conversion format specifier for
 299 .Xr printf 3
 300 was not of the form
 301 .Dl %[#][ ][{+,-}][0-9]*[.[0-9]*]?
 302 where
 303 .Dq ?\&
 304 must be one of
 305 .Dl [l]{d,i,o,u,x}
 306 or
 307 .Dl {c,e,f,g,D,E,G,O,U,X}
 308 .It "range error in conversion"
 309 A value to be printed fell outside the range of the data type
 310 associated with the requested output format.
 311 .It "too many conversions"
 312 More than one conversion format specifier has been supplied,
 313 but only one is allowed.
 314 .El
 315 .Sh SEE ALSO
 316 .Xr ed 1 ,
 317 .Xr expand 1 ,
 318 .Xr rs 1 ,
 319 .Xr seq 1 ,
 320 .Xr yes 1 ,
 321 .Xr arc4random 3 ,
 322 .Xr printf 3 ,
 323 .Xr random 3
 324 .Sh HISTORY
 325 The
 326 .Nm
 327 utility first appeared in
 328 .Bx 4.2 .
 329 .Sh AUTHORS
 330 .An John A. Kunze