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