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