Add a simple tool to generate a sequence of numbers, without all the
[dragonfly.git] / usr.bin / seq / seq.1
1 .\"
2 .\" Copyright (c) 2005 The DragonFly Project.  All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to The DragonFly Project
5 .\" Brian Ginsbach.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of The DragonFly Project nor the names of its
16 .\"    contributors may be used to endorse or promote products derived
17 .\"    from this software without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" $DragonFly: src/usr.bin/seq/seq.1,v 1.1 2005/01/22 19:09:40 joerg Exp $
33 .\"
34 .Dd January 17, 2005
35 .Dt SEQ 1
36 .Os
37 .Sh NAME
38 .Nm seq
39 .Nd print sequences of numbers
40 .Sh SYNOPSIS
41 .Nm
42 .Op Fl f Ar format
43 .Op Fl s Ar string
44 .Op Fl t Ar string
45 .Op Fl w
46 .Op Ar first Op Ar incr
47 .Ar last
48 .Sh DESCRIPTION
49 The
50 .Nm
51 utility prints a sequence of numbers, one per line
52 .Pq default ,
53 from
54 .Ar first 
55 .Pq default 1 ,
56 to near
57 .Ar last
58 as possible, in increments of
59 .Ar incr
60 .Pq default 1 .
61 When
62 .Ar first
63 is larger than
64 .Ar last
65 the default
66 .Ar incr
67 is -1.
68 .Pp
69 All numbers are interpreted as floating point.
70 .Pp
71 Normally integer values are printed as decimal integers.
72 .Pp
73 The
74 .Nm
75 utility accepts the following options:
76 .Bl -tag -width Ar
77 .It Fl f Ar format
78 Use a
79 .Xr printf 3
80 style
81 .Ar format
82 to print each number.  Only the
83 .Cm e ,
84 .Cm E ,
85 .Cm f ,
86 .Cm g ,
87 .Cm G ,
88 and
89 .Cm %
90 conversion characters are valid, along with any optional
91 flags and an optional numeric mimimum field width or precision.
92 The
93 .Ar format
94 can contain character escape sequences in backslash notation as
95 defined in 
96 .St -ansiC .
97 The default is
98 .Cm %g .
99 .It Fl s Ar string
100 Use
101 .Ar string
102 to separate numbers.
103 The
104 .Ar string
105 can contain character escape sequences in backslash notation as
106 defined in 
107 .St -ansiC .
108 The default is
109 .Cm \en .
110 .It Fl t Ar string
111 Use
112 .Ar string
113 to terminate sequence of numbers.
114 The
115 .Ar string
116 can contain character escape sequences in backslash notation as
117 defined in 
118 .St -ansiC .
119 This option is useful when the default separator
120 does not contain a
121 .Cm \en .
122 .It Fl w
123 Equalize the widths of all numbers by padding with zeros as necessary.
124 This option has no effect with the
125 .Fl f
126 option.
127 If any sequence numbers will be printed in exponential notation,
128 the default conversion is changed to
129 .Cm %e .
130 .El
131 .Pp
132 The
133 .Nm
134 utility exits 0 on success and non-zero if an error occurs.
135 .Sh EXAMPLES
136 .Bd -literal -offset indent
137 seq 1 3
138 1
139 2
140 3
141
142 seq 3 1
143 3
144 2
145 1
146
147 seq -w 0 .05 .1
148 0.00
149 0.05
150 0.10
151 .Ed
152 .Sh SEE ALSO
153 .Xr jot 1 ,
154 .Xr printf 1 ,
155 .Xr printf 3
156 .Sh HISTORY
157 The
158 .Nm
159 command first appeared in
160 .Tn "Plan 9 from Bell Labs" .
161 A
162 .Nm
163 command appeared in
164 .Nx 3.0 .
165 This command was based on the command of the same name in
166 .Tn "Plan 9 from Bell Labs"
167 and the
168 .Tn GNU
169 core utilities.
170 The 
171 .Tn GNU
172 .Nm
173 command first appeared in the 1.13 shell utilities release.
174 .Sh BUGS
175 The 
176 .Fl w
177 option does not handle the transition from pure floating point
178 to exponent representation very well.
179 The
180 .Nm
181 command is not bug for bug compatible with the
182 .Tn "Plan 9 from Bell Labs"
183 or 
184 .Tn GNU
185 versions of
186 .Nm .