author | viric@llimona |
Fri, 13 Apr 2007 20:52:28 +0200 | |
changeset 127 | c620eacd7630 |
parent 120 | 790bc4cecd3b |
child 142 | f78c77997a5e |
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: |
|
15 |
.BI "[\-KCLhV] |
|
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 ]] |
|
24 |
.BI "[\-U <"id - id >] |
|
25 |
.sp |
|
26 |
Options: |
|
27 |
.BI "[\-nfgm]" |
|
28 |
||
29 |
.SH DESCRIPTION |
|
89 | 30 |
.B ts |
31 |
will run by default a per user unix task queue. The user can add commands to |
|
78 | 32 |
the queue, watch that queue at any moment, and look at the task results |
33 |
(actually, standard output and exit error). |
|
34 |
.SH SIMPLE USE |
|
35 |
Calling |
|
36 |
.B ts |
|
37 |
with a command will add that command to the queue, and calling it without |
|
38 |
commands or parameters will show the task list. |
|
39 |
.SH COMMAND OPTIONS |
|
40 |
When adding a job to ts, we can specify how it will be run and how will the |
|
41 |
results be collected: |
|
42 |
.TP |
|
43 |
.B "\-n" |
|
44 |
Don't store the standard output/error in a file at |
|
45 |
.B $TMPDIR |
|
46 |
- let it use the |
|
47 |
file descriptors decided by the calling process. If it is not used, the |
|
48 |
.B jobid |
|
49 |
for the new task will be outputed to stdout. |
|
50 |
.TP |
|
51 |
.B "\-g" |
|
52 |
Pass the output through gzip (only if |
|
53 |
.B \-n |
|
54 |
). Note that the output files will not |
|
55 |
have a .gz extension. |
|
56 |
.TP |
|
57 |
.B "\-f" |
|
58 |
Don't put the task into background. Wait the queue and the command run without |
|
59 |
getting detached of the terminal. The exit code will be that of the command, and |
|
60 |
if used together with \-n, no result will be stored in the queue. |
|
61 |
.TP |
|
62 |
.B "\-m" |
|
63 |
Mail the results of the command (output and exit code) to |
|
64 |
.B $TS_MAILTO |
|
65 |
, or to the |
|
66 |
.B $USER |
|
67 |
using |
|
68 |
.B /usr/sbin/sendmail. |
|
69 |
Look at |
|
70 |
.B ENVIRONMENT. |
|
71 |
.SH ACTIONS |
|
72 |
Instead of giving a new command, we can use the parameters for other purposes: |
|
73 |
.TP |
|
74 |
.B "\-K" |
|
75 |
Kill the |
|
76 |
.B ts |
|
77 |
server for the calling client. This will remove the unix socket and |
|
78 |
all the |
|
79 |
.B ts |
|
80 |
processes related to the queue. This will not kill the command being |
|
81 |
run at that time. |
|
96 | 82 |
|
83 |
It's not reliable to think that |
|
84 |
.B ts -K |
|
85 |
will finish when the server is really killed. By now it's a race condition. |
|
78 | 86 |
.TP |
87 |
.B "\-C" |
|
88 |
Clear the results of finished jobs from the queue. |
|
89 |
.TP |
|
90 |
.B "\-l" |
|
91 |
Show the list of jobs - to be run, running and finished - for the current queue. |
|
92 |
This is the default behaviour if |
|
93 |
.B ts |
|
94 |
is called without options. |
|
95 |
.TP |
|
96 |
.B "\-t [id]" |
|
97 |
Run the system's tail to the output file of the named job, or the last |
|
98 |
running/run if not specified. |
|
99 |
.TP |
|
100 |
.B "\-c [id]" |
|
101 |
Run the system's cat to the output file of the named job, or the last |
|
102 |
running/run if not specified. |
|
103 |
.TP |
|
104 |
.B "\-p [id]" |
|
105 |
Show the pid of the named job, or the last running/run if not specified. |
|
106 |
.TP |
|
107 |
.B "\-o [id]" |
|
108 |
Show the output file name of the named job, or the last running/run |
|
109 |
if not specified. |
|
110 |
.TP |
|
111 |
.B "\-s [id]" |
|
112 |
Show the job state of the named job, or the last in the queue. |
|
113 |
.TP |
|
114 |
.B "\-r [id]" |
|
115 |
Remove the named job, or the last in the queue. |
|
116 |
.TP |
|
117 |
.B "\-w [id]" |
|
118 |
Wait for the named job, or for the last in the queue. |
|
119 |
.TP |
|
120 |
.B "\-u [id]" |
|
121 |
Make the named job (or the last in the queue) urgent - this means that it goes |
|
122 |
forward in the queue so it can run as soon as possible. |
|
123 |
.TP |
|
124 |
.B "\-U <id-id>" |
|
125 |
Interchange the queue positions of the named jobs (separated by a hyphen and no |
|
126 |
spaces). |
|
127 |
.TP |
|
128 |
.B "\-h" |
|
129 |
Show help on standard output. |
|
130 |
.TP |
|
131 |
.B "\-V" |
|
132 |
Show the program version. |
|
133 |
.SH ENVIRONMENT |
|
134 |
.TP |
|
135 |
.B "TS_MAXFINISHED" |
|
136 |
Limit the number of job results (finished tasks) you want in the queue. Use this |
|
137 |
option if you're tired of |
|
138 |
.B \-C. |
|
139 |
.TP |
|
89 | 140 |
.B "TS_ONFINISH" |
141 |
If the variable exists pointing to an executable, it will be run after the |
|
142 |
queued jobs. It uses execlp, so |
|
143 |
.B PATH |
|
93 | 144 |
is used if there are no slashes in the variable content. The executable is run |
145 |
with four parameters: |
|
146 |
.B jobid |
|
147 |
.B errorlevel |
|
148 |
.B output_filename |
|
149 |
and |
|
150 |
.B command. |
|
89 | 151 |
.TP |
78 | 152 |
.B "TMPDIR" |
153 |
As the program output and the unix socket are thought to be stored in a |
|
154 |
temporary directory, |
|
155 |
.B TMPDIR |
|
156 |
will be used if defined, or |
|
157 |
.B /tmp |
|
158 |
otherwise. |
|
159 |
.TP |
|
160 |
.B "TS_SOCKET" |
|
161 |
Each queue has a related unix socket. You can specify the socket path with this |
|
162 |
environment variable. This way, you can have a queue for your heavy disk |
|
163 |
operations, another for heavy use of ram., and have a simple script/alias |
|
164 |
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
|
165 |
.B $TMPDIR/socket-ts.[uid]. |
78 | 166 |
.TP |
167 |
.B "TS_MAILTO" |
|
168 |
Send the letters with job results to the address specified in this variable. |
|
169 |
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
|
170 |
.B $USER |
361b08d33762
$USER is no more used for crating the socket path. Now the UID is used.
viric@llimona
parents:
100
diff
changeset
|
171 |
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
|
172 |
.B nobody. |
78 | 173 |
The system |
174 |
.B /usr/sbin/sendmail |
|
175 |
is used. The |
|
176 |
job outputs are not sent as an attachment, so understand the consequences if you |
|
177 |
use the |
|
178 |
.B \-gm |
|
179 |
flags together. |
|
180 |
.TP |
|
181 |
.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
|
182 |
As seen above, it's used for the mail destination if |
78 | 183 |
.B TS_MAILTO |
184 |
is not specified. |
|
120 | 185 |
.TP |
186 |
.B "TS_SAVELIST" |
|
187 |
If it's defined when starting the queue server (probably the first |
|
188 |
.B ts |
|
189 |
command run), on SIGTERM the queue status will be saved to the file pointed |
|
190 |
by this environment variable - for example, at system shutdown. |
|
78 | 191 |
.SH BUGS |
192 |
If you want to run complex commands, you may want to run them through |
|
193 |
.B sh -c 'commands...' |
|
194 |
Also, remember that stdin/stdout/stderr will be detached, so |
|
195 |
don't use your shell's redirection operators when you put a job into background. |
|
80
be0fb7e56061
New Changelog, updated README, and the manpage.
viric@llimona
parents:
78
diff
changeset
|
196 |
|
93 | 197 |
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
|
198 |
.B /tmp/ts.error |
05004c52ecff
Better error reports on internal handled errors.
viric@llimona
parents:
89
diff
changeset
|
199 |
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
|
200 |
|
78 | 201 |
.SH SEE ALSO |
202 |
.BR at (1) |
|
203 |
.SH AUTHOR |
|
204 |
Lluis Batlle i Rossell |
|
205 |
.SH NOTES |
|
206 |
This page describes |
|
207 |
.B ts |
|
127 | 208 |
as in version 0.4. Other versions my differ. The file |
80
be0fb7e56061
New Changelog, updated README, and the manpage.
viric@llimona
parents:
78
diff
changeset
|
209 |
.B TRICKS |
be0fb7e56061
New Changelog, updated README, and the manpage.
viric@llimona
parents:
78
diff
changeset
|
210 |
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
|
211 |
.B ts. |