1TS(1) General Commands Manual TS(1)
2
6 ts - task spooler. A simple unix batch system
7
9 ts [actions] [options] [command...]
10 Actions: [-KClhV] [-t [id]] [-c [id]] [-p [id]] [-o [id]] [-s [id]] [-r
12 [id]] [-w [id]] [-k [id]] [-u [id]] [-i [id]] [-U <id-id>] [-S [num]]
13 Options: [-nfgmd] [-L <label>] [-D <id>]
15
18 ts will run by default a per user unix task queue. The user can add
19 commands to the queue, watch that queue at any moment, and look at the
20 task results (actually, standard output and exit error).
21
23 Calling ts with a command will add that command to the queue, and call‐
24 ing it without commands or parameters will show the task list.
25
27 When adding a job to ts, we can specify how it will be run and how will
28 the results be collected:
29 -n Do not store the standard output/error in a file at $TMPDIR -
31 let it use the file descriptors decided by the calling process.
32 If it is not used, the jobid for the new task will be outputed
33 to stdout.
34 -g Pass the output through gzip (only if -n ). Note that the output
36 files will not have a .gz extension.
37 -f Don not put the task into background. Wait the queue and the
39 command run without getting detached of the terminal. The exit
40 code will be that of the command, and if used together with -n,
41 no result will be stored in the queue.
42 -m Mail the results of the command (output and exit code) to
44 $TS_MAILTO , or to the $USER using /usr/sbin/sendmail. Look at
45 ENVIRONMENT.
46 -L <label>
48 Add a label to the task, which will appear next to its command
49 when listing the queue. It makes more comfortable distinguishing
50 similar commands with different goals.
51 -d Run the command only if the command before finished well (error‐
53 level = 0). This new task enqueued depends on the result of the
54 previous command. If the task is not run, it is considered as
55 failed for further dependencies.
56 -D <id>
58 Run the command only if the job of given id finished well (er‐
59 rorlevel = 0). This new task enqueued depends on the result of
60 the previous command. If the task is not run, it is considered
61 as failed for further dependencies. If the server doesn't have
62 the job id in its list, it will be considered as if the job
63 failed.
64 -B In the case the queue is full (due to TS_MAXCONN or system lim‐
66 its), by default ts will block the enqueuing command. Using -B,
67 if the queue is full it will exit returning the value 2 instead
68 of blocking.
69 -E Keep two different output files for the command stdout and
71 stderr. stdout goes to the file announced by ts (look at -o),
72 and stderr goes to the stdout file with an additional ".e". For
73 example, /tmp/ts-out.SKsDw8 and /tmp/ts-out.SKsDw8.e. Only the
74 stdout file gets created with mkstemp, ensuring it does not
75 overwrite any other; the ".e" will be overwritten if it existed.
76 -N <num>
78 Run the command only if there are num slots free in the queue.
79 Without it, the job will run if there is one slot free. For ex‐
80 ample, if you use the queue to feed cpu cores, and you know that
81 a job will take two cores, with -N you can let ts know that.
82
84 Instead of giving a new command, we can use the parameters for other
85 purposes:
86 -K Kill the ts server for the calling client. This will remove the
88 unix socket and all the ts processes related to the queue. This
89 will not kill the command being run at that time.
90 It is not reliable to think that ts -K will finish when the
92 server is really killed. By now it is a race condition.
93 -C Clear the results of finished jobs from the queue.
95 -l Show the list of jobs - to be run, running and finished - for
97 the current queue. This is the default behaviour if ts is
98 called without options.
99 -t [id]
101 Show the last ten lines of the output file of the named job, or
102 the last running/run if not specified. If the job is still run‐
103 ning, it will keep on showing the additional output until the
104 job finishes. On exit, it returns the errorlevel of the job, as
105 in -c.
106 -c [id]
108 Run the system's cat to the output file of the named job, or the
109 last running/run if not specified. It will block until all the
110 output can be sent to standard output, and will exit with the
111 job errorlevel as in -c.
112 -p [id]
114 Show the pid of the named job, or the last running/run if not
115 specified.
116 -o [id]
118 Show the output file name of the named job, or the last run‐
119 ning/run if not specified.
120 -s [id]
122 Show the job state of the named job, or the last in the queue.
123 -r [id]
125 Remove the named job, or the last in the queue.
126 -w [id]
128 Wait for the named job, or for the last in the queue.
129 -k [id]
131 Kill the process group of the named job (SIGTERM), or the last
132 running/run job if not specified. Equivalent to kill -- -`ts
133 -p`
134 -u [id]
136 Make the named job (or the last in the queue) urgent - this
137 means that it goes forward in the queue so it can run as soon as
138 possible.
139 -i [id]
141 Show information about the named job (or the last run). It will
142 show the command line, some times related to the task, and also
143 any information resulting from TS_ENV (Look at ENVIRONMENT).
144 -U <id-id>
146 Interchange the queue positions of the named jobs (separated by
147 a hyphen and no spaces).
148 -h Show help on standard output.
150 -V Show the program version.
152
154 ts by default offers a queue where each job runs only after the previ‐
155 ous finished. Nevertheless, you can change the maximum number of jobs
156 running at once with the -S [num] parameter. We call that number the
157 amount of slots. You can also set the initial number of jobs with the
158 environment variable TS_SLOTS . When increasing this setting, queued
159 waiting jobs will be run at once until reaching the maximum set. When
160 decreasing this setting, no other job will be run until it can meet the
161 amount of running jobs set. When using an amount of slots greater
162 than 1, the action of some commands may change a bit. For example, -t
163 without jobid will tail the first job running, and -d will try to set
164 the dependency with the last job added.
165 -S [num]
167 Set the maximum amount of running jobs at once. If you don't
168 specify num it will return the maximum amount of running jobs
169 set.
170
172 TS_MAXFINISHED
173 Limit the number of job results (finished tasks) you want in the
174 queue. Use this option if you are tired of -C.
175 TS_MAXCONN
177 The maximum number of ts server connections to clients. This
178 will make the ts clients block until connections are freed. This
179 helps, for example, on systems with a limited number of pro‐
180 cesses, because each job waiting in the queue remains as a
181 process. This variable has to be set at server start, and cannot
182 be modified later.
183 TS_ONFINISH
185 If the variable exists pointing to an executable, it will be run
186 by the client after the queued job. It uses execlp, so PATH is
187 used if there are no slashes in the variable content. The exe‐
188 cutable is run with four parameters: jobid errorlevel out‐
189 put_filename and command.
190 TMPDIR As the program output and the unix socket are thought to be
192 stored in a temporary directory, TMPDIR will be used if defined,
193 or /tmp otherwise.
194 TS_SOCKET
196 Each queue has a related unix socket. You can specify the socket
197 path with this environment variable. This way, you can have a
198 queue for your heavy disk operations, another for heavy use of
199 ram., and have a simple script/alias wrapper over ts for those
200 special queues. If it is not specified, it will be $TM‐
201 PDIR/socket-ts.[uid].
202 TS_SLOTS
204 Set the number of slots at the start of the server, similar to
205 -S, but the contents of the variable are read only when running
206 the first instance of ts.
207 TS_MAILTO
209 Send the letters with job results to the address specified in
210 this variable. Otherwise, they are sent to $USER or if not de‐
211 fined, nobody. The system /usr/sbin/sendmail is used. The job
212 outputs are not sent as an attachment, so understand the conse‐
213 quences if you use the -gm flags together.
214 USER As seen above, it is used for the mail destination if TS_MAILTO
216 is not specified.
217 TS_SAVELIST
219 If it is defined when starting the queue server (probably the
220 first ts command run), on SIGTERM the queue status will be saved
221 to the file pointed by this environment variable - for example,
222 at system shutdown.
223 TS_ENV This has a command to be run at enqueue time through /bin/sh.
225 The output of the command will be readable through the option
226 -i. You can use a command which shows relevant environment for
227 the command run. For example, you may use
228 TS_ENV='pwd;set;mount'.
229
231 /tmp/ts.error
232 if ts finds any internal problem, you should find an error re‐
233 port there. Please send this to the author as part of the bug
234 report.
235
238 ts expects a simple command line. It does not start a shell parser. If
239 you want to run complex shell commands, you may want to run them
240 through sh -c 'commands...' Also, remember that stdin/stdout/stderr
241 will be detached, so do not use your shell's redirection operators when
242 you put a job into background. You can use them inside the sh -c in
243 order to set redirections to the command run.
244 If an internal problem is found in runtime, a file /tmp/ts.error is
246 created, which you can submit to the developer in order to fix the bug.
247
250 at(1)
251
253 Lluis Batlle i Rossell
254
256 This page describes ts as in version 1.0. Other versions may differ.
257 The file TRICKS found in the distribution package can show some ideas
258 on special uses of ts.
259Task Spooler 1.0.2 2020-12 TS(1)