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