author | viric@mandarina |
Wed, 18 Feb 2009 23:25:21 +0100 | |
changeset 267 | 11631dd11ff8 |
parent 266 | e35af91aa426 |
child 280 | d207fb747144 |
permissions | -rw-r--r-- |
78 | 1 |
.\" Copyright LluĂs Batlle |
2 |
.\" |
|
3 |
.\" This file may be copied under the conditions described |
|
4 |
.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 |
|
5 |
.\" that should have been distributed together with this file. |
|
6 |
.\" |
|
7 |
.\" Note: I took the gnu 'ls' man page as an example. |
|
266
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
8 |
.TH TS 1 2009-02 "Task Spooler 0.6.3" |
78 | 9 |
.SH NAME |
10 |
ts \- task spooler. A simple unix batch system |
|
11 |
.SH SYNOPSIS |
|
12 |
.BI "ts [" actions "] [" options "] [" command... ] |
|
13 |
.sp |
|
14 |
Actions: |
|
160 | 15 |
.BI "[\-KClhV] |
78 | 16 |
.BI "[\-t ["id ]] |
17 |
.BI "[\-c ["id ]] |
|
18 |
.BI "[\-p ["id ]] |
|
19 |
.BI "[\-o ["id ]] |
|
20 |
.BI "[\-s ["id ]] |
|
21 |
.BI "[\-r ["id ]] |
|
22 |
.BI "[\-w ["id ]] |
|
23 |
.BI "[\-u ["id ]] |
|
159 | 24 |
.BI "[\-i ["id ]] |
78 | 25 |
.BI "[\-U <"id - id >] |
253
e9b153f4ae40
Making "-S" to return the number of slots set, if without additional argument.
viric@mandarina
parents:
243
diff
changeset
|
26 |
.BI "[\-S ["num ]] |
78 | 27 |
.sp |
28 |
Options: |
|
159 | 29 |
.BI "[\-nfgmd]" |
160 | 30 |
.BI "[\-L <"label >] |
266
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
31 |
.BI "[\-D <"id >] |
78 | 32 |
|
33 |
.SH DESCRIPTION |
|
89 | 34 |
.B ts |
35 |
will run by default a per user unix task queue. The user can add commands to |
|
78 | 36 |
the queue, watch that queue at any moment, and look at the task results |
37 |
(actually, standard output and exit error). |
|
38 |
.SH SIMPLE USE |
|
39 |
Calling |
|
40 |
.B ts |
|
41 |
with a command will add that command to the queue, and calling it without |
|
42 |
commands or parameters will show the task list. |
|
43 |
.SH COMMAND OPTIONS |
|
44 |
When adding a job to ts, we can specify how it will be run and how will the |
|
45 |
results be collected: |
|
46 |
.TP |
|
47 |
.B "\-n" |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
48 |
Do not store the standard output/error in a file at |
78 | 49 |
.B $TMPDIR |
50 |
- let it use the |
|
51 |
file descriptors decided by the calling process. If it is not used, the |
|
52 |
.B jobid |
|
53 |
for the new task will be outputed to stdout. |
|
54 |
.TP |
|
55 |
.B "\-g" |
|
56 |
Pass the output through gzip (only if |
|
57 |
.B \-n |
|
58 |
). Note that the output files will not |
|
59 |
have a .gz extension. |
|
60 |
.TP |
|
61 |
.B "\-f" |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
62 |
Don not put the task into background. Wait the queue and the command run without |
78 | 63 |
getting detached of the terminal. The exit code will be that of the command, and |
64 |
if used together with \-n, no result will be stored in the queue. |
|
65 |
.TP |
|
66 |
.B "\-m" |
|
67 |
Mail the results of the command (output and exit code) to |
|
68 |
.B $TS_MAILTO |
|
69 |
, or to the |
|
70 |
.B $USER |
|
71 |
using |
|
72 |
.B /usr/sbin/sendmail. |
|
73 |
Look at |
|
74 |
.B ENVIRONMENT. |
|
159 | 75 |
.TP |
76 |
.B "\-L <label>" |
|
77 |
Add a label to the task, which will appear next to its command when listing |
|
78 |
the queue. It makes more comfortable distinguishing similar commands with |
|
79 |
different goals. |
|
80 |
.TP |
|
81 |
.B "\-d" |
|
82 |
Run the command only if the command before finished well (errorlevel = 0). This new |
|
83 |
task enqueued depends on the result of the previous command. If the task is not run, |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
84 |
it is considered as failed for further dependencies. |
266
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
85 |
.TP |
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
86 |
.B "\-D <id>" |
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
87 |
Run the command only if the job of given id finished well (errorlevel = 0). This new |
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
88 |
task enqueued depends on the result of the previous command. If the task is not run, |
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
89 |
it is considered as failed for further dependencies. |
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
90 |
If the server doesn't have the job id in its list, it will be considered |
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
91 |
as if the job failed. |
78 | 92 |
.SH ACTIONS |
93 |
Instead of giving a new command, we can use the parameters for other purposes: |
|
94 |
.TP |
|
95 |
.B "\-K" |
|
96 |
Kill the |
|
97 |
.B ts |
|
98 |
server for the calling client. This will remove the unix socket and |
|
99 |
all the |
|
100 |
.B ts |
|
101 |
processes related to the queue. This will not kill the command being |
|
102 |
run at that time. |
|
96 | 103 |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
104 |
It is not reliable to think that |
96 | 105 |
.B ts -K |
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
106 |
will finish when the server is really killed. By now it is a race condition. |
78 | 107 |
.TP |
108 |
.B "\-C" |
|
109 |
Clear the results of finished jobs from the queue. |
|
110 |
.TP |
|
111 |
.B "\-l" |
|
112 |
Show the list of jobs - to be run, running and finished - for the current queue. |
|
113 |
This is the default behaviour if |
|
114 |
.B ts |
|
115 |
is called without options. |
|
116 |
.TP |
|
117 |
.B "\-t [id]" |
|
184
a081c209c21b
Updating the makedeb code, and the manpage, according to 0.5
viric@llimona
parents:
164
diff
changeset
|
118 |
Show the last ten lines of the output file of the named job, or the last |
a081c209c21b
Updating the makedeb code, and the manpage, according to 0.5
viric@llimona
parents:
164
diff
changeset
|
119 |
running/run if not specified. If the job is still running, it will keep on |
a081c209c21b
Updating the makedeb code, and the manpage, according to 0.5
viric@llimona
parents:
164
diff
changeset
|
120 |
showing the additional output until the job finishes. On exit, it returns the |
a081c209c21b
Updating the makedeb code, and the manpage, according to 0.5
viric@llimona
parents:
164
diff
changeset
|
121 |
errorlevel of the job, as in \fB\-c\fR. |
78 | 122 |
.TP |
123 |
.B "\-c [id]" |
|
124 |
Run the system's cat to the output file of the named job, or the last |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
125 |
running/run if not specified. It will block until all the output can be |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
126 |
sent to standard output, and will exit with the job errorlevel as in |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
127 |
\fB\-c\fR. |
78 | 128 |
.TP |
129 |
.B "\-p [id]" |
|
130 |
Show the pid of the named job, or the last running/run if not specified. |
|
131 |
.TP |
|
132 |
.B "\-o [id]" |
|
133 |
Show the output file name of the named job, or the last running/run |
|
134 |
if not specified. |
|
135 |
.TP |
|
136 |
.B "\-s [id]" |
|
137 |
Show the job state of the named job, or the last in the queue. |
|
138 |
.TP |
|
139 |
.B "\-r [id]" |
|
140 |
Remove the named job, or the last in the queue. |
|
141 |
.TP |
|
142 |
.B "\-w [id]" |
|
143 |
Wait for the named job, or for the last in the queue. |
|
144 |
.TP |
|
145 |
.B "\-u [id]" |
|
146 |
Make the named job (or the last in the queue) urgent - this means that it goes |
|
147 |
forward in the queue so it can run as soon as possible. |
|
148 |
.TP |
|
159 | 149 |
.B "\-i [id]" |
150 |
Show information about the named job (or the last run). It will show the command line, |
|
151 |
some times related to the task, and also any information resulting from |
|
152 |
\fBTS_ENV\fR (Look at \fBENVIRONMENT\fR). |
|
153 |
.TP |
|
78 | 154 |
.B "\-U <id-id>" |
155 |
Interchange the queue positions of the named jobs (separated by a hyphen and no |
|
156 |
spaces). |
|
157 |
.TP |
|
158 |
.B "\-h" |
|
159 |
Show help on standard output. |
|
160 |
.TP |
|
161 |
.B "\-V" |
|
162 |
Show the program version. |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
163 |
.SH MULTI-SLOT |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
164 |
.B ts |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
165 |
by default offers a queue where each job runs only after the previous finished. |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
166 |
Nevertheless, you can change the maximum number of jobs running at once with |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
167 |
the |
253
e9b153f4ae40
Making "-S" to return the number of slots set, if without additional argument.
viric@mandarina
parents:
243
diff
changeset
|
168 |
.B "\-S [num]" |
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
169 |
parameter. We call that number the |
243 | 170 |
\fIamount of slots\fR. You can also set the initial number of jobs with |
171 |
the environment variable |
|
172 |
.B "TS_SLOTS". |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
173 |
When increasing this setting, queued waiting jobs will be run |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
174 |
at once until reaching the maximum set. When decreasing this setting, no other |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
175 |
job will be run until it can meet the amount of running jobs set. |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
176 |
.BR |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
177 |
When using an amount of slots greater than 1, the action of some commands |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
178 |
may change a bit. For example, \fB\-t\fR without \fIjobid\fR will tail the first |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
179 |
job running, and \fB\-d\fR will try to set the dependency with the last job added. |
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
180 |
.TP |
253
e9b153f4ae40
Making "-S" to return the number of slots set, if without additional argument.
viric@mandarina
parents:
243
diff
changeset
|
181 |
.B "\-S [num]" |
e9b153f4ae40
Making "-S" to return the number of slots set, if without additional argument.
viric@mandarina
parents:
243
diff
changeset
|
182 |
Set the maximum amount of running jobs at once. If you don't specify |
e9b153f4ae40
Making "-S" to return the number of slots set, if without additional argument.
viric@mandarina
parents:
243
diff
changeset
|
183 |
.B num |
e9b153f4ae40
Making "-S" to return the number of slots set, if without additional argument.
viric@mandarina
parents:
243
diff
changeset
|
184 |
it will return the maximum amount of running jobs set. |
78 | 185 |
.SH ENVIRONMENT |
186 |
.TP |
|
187 |
.B "TS_MAXFINISHED" |
|
188 |
Limit the number of job results (finished tasks) you want in the queue. Use this |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
189 |
option if you are tired of |
78 | 190 |
.B \-C. |
191 |
.TP |
|
89 | 192 |
.B "TS_ONFINISH" |
142 | 193 |
If the variable exists pointing to an executable, it will be run by the client |
194 |
after the queued job. It uses execlp, so |
|
89 | 195 |
.B PATH |
93 | 196 |
is used if there are no slashes in the variable content. The executable is run |
197 |
with four parameters: |
|
198 |
.B jobid |
|
199 |
.B errorlevel |
|
200 |
.B output_filename |
|
201 |
and |
|
202 |
.B command. |
|
89 | 203 |
.TP |
78 | 204 |
.B "TMPDIR" |
205 |
As the program output and the unix socket are thought to be stored in a |
|
206 |
temporary directory, |
|
207 |
.B TMPDIR |
|
208 |
will be used if defined, or |
|
209 |
.B /tmp |
|
210 |
otherwise. |
|
211 |
.TP |
|
212 |
.B "TS_SOCKET" |
|
213 |
Each queue has a related unix socket. You can specify the socket path with this |
|
214 |
environment variable. This way, you can have a queue for your heavy disk |
|
215 |
operations, another for heavy use of ram., and have a simple script/alias |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
216 |
wrapper over ts for those special queues. If it is not specified, it will be |
119
361b08d33762
$USER is no more used for crating the socket path. Now the UID is used.
viric@llimona
parents:
100
diff
changeset
|
217 |
.B $TMPDIR/socket-ts.[uid]. |
78 | 218 |
.TP |
243 | 219 |
.B "TS_SLOTS" |
220 |
Set the number of slots at the start of the server, similar to |
|
221 |
.B \-S, |
|
222 |
but the contents of the variable are read only when running |
|
223 |
the first instance of |
|
224 |
.B ts. |
|
225 |
.TP |
|
78 | 226 |
.B "TS_MAILTO" |
227 |
Send the letters with job results to the address specified in this variable. |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
228 |
Otherwise, they are sent to |
119
361b08d33762
$USER is no more used for crating the socket path. Now the UID is used.
viric@llimona
parents:
100
diff
changeset
|
229 |
.B $USER |
361b08d33762
$USER is no more used for crating the socket path. Now the UID is used.
viric@llimona
parents:
100
diff
changeset
|
230 |
or if not defined, |
361b08d33762
$USER is no more used for crating the socket path. Now the UID is used.
viric@llimona
parents:
100
diff
changeset
|
231 |
.B nobody. |
78 | 232 |
The system |
233 |
.B /usr/sbin/sendmail |
|
234 |
is used. The |
|
235 |
job outputs are not sent as an attachment, so understand the consequences if you |
|
236 |
use the |
|
237 |
.B \-gm |
|
238 |
flags together. |
|
239 |
.TP |
|
240 |
.B "USER" |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
241 |
As seen above, it is used for the mail destination if |
78 | 242 |
.B TS_MAILTO |
243 |
is not specified. |
|
120 | 244 |
.TP |
245 |
.B "TS_SAVELIST" |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
246 |
If it is defined when starting the queue server (probably the first |
120 | 247 |
.B ts |
248 |
command run), on SIGTERM the queue status will be saved to the file pointed |
|
249 |
by this environment variable - for example, at system shutdown. |
|
159 | 250 |
.TP |
251 |
.B "TS_ENV" |
|
252 |
This has a command to be run at enqueue time through |
|
253 |
\fB/bin/sh\fR. The output of the command will be readable through the option |
|
254 |
\fB\-i\fR. You can use a command which shows relevant environment for the command run. |
|
255 |
For example, you may use \fBTS_ENV='pwd;set;mount'\fR. |
|
142 | 256 |
.SH FILES |
257 |
.TP |
|
258 |
.B /tmp/ts.error |
|
259 |
if |
|
260 |
.B ts |
|
261 |
finds any internal problem, you should find an error report there. |
|
262 |
Please send this to the author as part of the bug report. |
|
263 |
||
78 | 264 |
.SH BUGS |
142 | 265 |
.B ts |
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
266 |
expects a simple command line. It does not start a shell parser. |
142 | 267 |
If you want to run complex shell commands, you may want to run them through |
78 | 268 |
.B sh -c 'commands...' |
269 |
Also, remember that stdin/stdout/stderr will be detached, so |
|
232
7201bb3ee30d
Updating the man page for 0.6 (also removed some verbal short forms)
llbatlle@taga
parents:
184
diff
changeset
|
270 |
do not use your shell's redirection operators when you put a job into background. |
142 | 271 |
You can use them inside the |
272 |
.B sh -c |
|
273 |
in order to set redirections to the command run. |
|
80
be0fb7e56061
New Changelog, updated README, and the manpage.
viric@llimona
parents:
78
diff
changeset
|
274 |
|
93 | 275 |
If an internal problem is found in runtime, a file |
92
05004c52ecff
Better error reports on internal handled errors.
viric@llimona
parents:
89
diff
changeset
|
276 |
.B /tmp/ts.error |
05004c52ecff
Better error reports on internal handled errors.
viric@llimona
parents:
89
diff
changeset
|
277 |
is created, which you can submit to the developer in order to fix the bug. |
05004c52ecff
Better error reports on internal handled errors.
viric@llimona
parents:
89
diff
changeset
|
278 |
|
78 | 279 |
.SH SEE ALSO |
280 |
.BR at (1) |
|
281 |
.SH AUTHOR |
|
282 |
Lluis Batlle i Rossell |
|
283 |
.SH NOTES |
|
284 |
This page describes |
|
285 |
.B ts |
|
266
e35af91aa426
Fixing the help messages and man page for 0.6.3.
viric@mandarina
parents:
257
diff
changeset
|
286 |
as in version 0.6.3. Other versions may differ. The file |
80
be0fb7e56061
New Changelog, updated README, and the manpage.
viric@llimona
parents:
78
diff
changeset
|
287 |
.B TRICKS |
be0fb7e56061
New Changelog, updated README, and the manpage.
viric@llimona
parents:
78
diff
changeset
|
288 |
found in the distribution package can show some ideas on special uses of |
be0fb7e56061
New Changelog, updated README, and the manpage.
viric@llimona
parents:
78
diff
changeset
|
289 |
.B ts. |