source: trunk/stopos.man @ 20

Last change on this file since 20 was 7, checked in by willem, 11 years ago

willem

File size: 5.3 KB
Line 
1.\"
2.\" Copyright 2013 Willem Vermin, SURFsara
3.\"
4.\" Licensed under the Apache License, Version 2.0 (the "License");
5.\" you may not use this file except in compliance with the License.
6.\" You may obtain a copy of the License at
7.\"
8.\"     http://www.apache.org/licenses/LICENSE-2.0
9.\"
10.\" Unless required by applicable law or agreed to in writing, software
11.\" distributed under the License is distributed on an "AS IS" BASIS,
12.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13.\" See the License for the specific language governing permissions and
14.\" limitations under the License.
15.\"
16
17.TH STOPOS 1 
18.SH NAME
19stopos \- alias to call the program stoposclient and eval it's output
20.SH SYNOPSIS
21.B stopos
22\fB\ -h,--help  \fP 
23.P 8
24.B stopos
25\fB\ -v,--version  \fP 
26.P 8
27.B stopos
28\fB\ create \fP   [\fB -p,--pool POOL\fP ]
29.P 8
30.B stopos
31\fB\ status \fP   [\fB -p,--pool POOL\fP]
32.P 8
33.B stopos
34\fB\ purge \fP    [\fB -p,--pool POOL\fP ]
35.P 8
36.B stopos
37\fB\ pools \fP
38.P 8
39.B stopos
40\fB\ add   \fP    [\fB -p,--pool POOL\fP ] [\fB FILENAME \fB]
41.P 8
42.B stopos
43\fB\ next  \fP    [\fB -p,--pool POOL\fP ] [\fB -m,--multi \fB]
44.P 8
45.B stopos
46\fB\ remove \fP   [\fB -p,--pool POOL\fP] [\fB KEY \fP ]
47.P 8
48.B stopos
49\fB\ dump \fP     [\fB -p,--pool POOL\fP]
50.P 8
51The -q,--quiet flag supresses most output.
52.P 8
53.SH DESCRIPTION
54Stopos is an alias using the program stoposclient, an utility to store
55and retrieve text lines in a pool.
56In general, the
57text lines are used as command parameters, see Examples.
58.SH COMMANDS
59.TP 4
60.B -h,--help
61Prints usage information.
62.TP 4
63.B -v,--version
64Prints version.
65.TP 4
66.B create [ -p,--pool POOL ] [ FILENAME ]
67Creates new pool.
68A pool with the same name will be removed first.
69.TP 4
70.B status
71Prints to standard error       environment variable
72.br
73---------------------------------------------------
74.br
75total number of lines added      STOPOS_COUNT
76.br 
77number of lines present          STOPOS_PRESENT
78.br
79number of lines never committed  STOPOS_PRESENT0
80.TP 4
81.TP 4
82.B purge [-p,--pool POOL ]
83Removes the pool.
84.TP 4
85.B pools [-p,--pool POOL ]
86Lists on standard error the pools available. The environment
87variable STOPOS_VALUE is set accordingly.
88.TP 4
89.B add [ -p,--pool POOL ] [ FILENAME ]
90Adds lines from FILENAME, default from stdin.
91The maximum line length is 1024 characters.
92The environment variables STOPOS_RC and STOPS_KEY are set.
93.br
94NOTE: when stopos is reading from a pipe as in:
95.br
96   cat parmfile | stopos add
97.br
98no environment variables are set.
99.TP 4
100.B next [ -p,--pool POOL ] [ -m,--multi ]
101Gets the next line from the pool.
102The environment variables STOPOS_VALUE, STOPOS_COMMITTED and STOPOS_KEY are set,
103see ENVIRONMENT.
104By default, the same line in the pool will be
105produced only once. When all lines are commited, STOPS_RC will not
106be equal to OK. Using the --multi flag, the same line can be produced
107more than once, if necessary stopos will wrap around.
108This can be useful for dealing with crashed jobs.
109.TP 4
110.B remove [-p,--pool POOL ] [ KEY ]
111Removes the line with key KEY.
112If not specified on the commandline, the
113value of environment variable STOPOS_KEY is used.
114.TP 4
115.B dump  [-p,--pool POOL ]
116Reads the next available line, and puts it,
117preceded by it's key and number of commitments in environment variable
118STOPOS_VALUE. The first call will produce the first line.
119When all lines have been delivered, STOPOS_RC
120gets a value other than OK. A subsequent call will start the dump
121with the first line again.
122.SH OPTIONS
123.TP 4
124.B -p,--pool POOL
125POOL is a unique name of the pool.
126Default: pool.
127The name of the pool can also be set using the environment variable STOPOS_POOL. The command line flag has precedence.
128
129.SH ENVIRONMENT
130Stopos sets the following environment variables:
131.P
132.B STOPOS_RC
133if the value is OK, than no errors were found
134.P
135.B STOPOS_KEY
136contains the keyvalue of the line produced with the 'next' command, or
137the keyvalue of the line just added. The keyvalue (a short string) is
138guaranteed to be unique between to 'create"s' or between
139'create' and 'purge'
140.P
141.B STOPOS_COMMITTED
142contains the number of times the line has been committed
143.P
144.B STOPOS_VALUE
145contains the line produced by the 'next' command or the result of the 'pools' command
146.P
147.B STOPOS_COUNT STOPOS_PRESENT STOPOS_PRESENT0
148see the 'status' command above
149.P
150Stopos uses the following environment variables:
151.P
152.B STOPOS_POOL 
153see the description of the --pool flag under OPTIONS
154.P
155.B STOPOS_KEY 
156see the 'remove' flag above
157.P
158.B STOPOS_SERVER_URL 
159the url stopos uses to access the server, default DEFAULTSERVERURL
160
161.SH EXAMPLES
162.TP 4
163
164Create a pool with the first 10 lines from the man page of sed:
165
166 man sed | head > parmfile
167 stopos create
168 stopos add parmfile
169
170Get a line:
171
172 stopos next
173
174The environment variable STOPOS_VALUE contains now one of the
175first ten lines of the man page of sed.
176
177You can use this in a command like this:
178
179 eval "myparser $STOPOS_VALUE"
180
181The line can be removed by:
182
183 stopos remove
184
185Finally, the pool can be completely removed by:
186
187 stopos purge
188
189.SH FILES
190$HOME/.stopos/id
191.br
192This file is set by stopos to store an unique id, which, together
193with the login name, will be used to identify which pools are yours.
194.SH "SEE ALSO"
195sara-get-mem-size(1), sara-get-num-cores(1), stoposclient(1), stoposdump(1)
196.SH AUTHORS
197Willem Vermin
198.br
199.SH BUGS
200No bugs known yet.
Note: See TracBrowser for help on using the repository browser.