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