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