sgsh-readval.1

.TH SGSH-READVAL 1 "21 March 2013"
.\"
.\" (C) Copyright 2013 Diomidis Spinellis.  All rights reserved.
.\"
.\"  Licensed under the Apache License, Version 2.0 (the "License");
.\"  you may not use this file except in compliance with the License.
.\"  You may obtain a copy of the License at
.\"
.\"      http://www.apache.org/licenses/LICENSE-2.0
.\"
.\"  Unless required by applicable law or agreed to in writing, software
.\"  distributed under the License is distributed on an "AS IS" BASIS,
.\"  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\"  See the License for the specific language governing permissions and
.\"  limitations under the License.
.\"
.SH NAME
sgsh-readval \- data store client
.SH SYNOPSIS
\fBsgsh-readval\fP
[\fB\-c\fP | \fB-e\fP | \fB-l\fP]
[\fB\-nq\fP]
\fB\-s\fP \fIpath\fP
.SH DESCRIPTION
\fIsgsh-readval\fP is a data store client.
By default it will communicate with the store specified through
the path to a Unix domain socket,
ask to read the last (final) record written to that store,
and write the value on its standard output.
.PP
\fIsgsh-readval\fP is normally executed from within \fIsgsh\fP-generated scripts,
rather than through end-user commands.
This manual page serves mainly to document its operation and
the flags that can be used in \fIsgsh\fP scripts when reading from stores.

.SH OPTIONS
.IP "\fB\-c\fP
Read the current (rather than the last) value from the store.
If no complete record has been written into the store,
the operation will block until such a record is available.

.IP "\fB\-e\fP
Read the current or an empty value from the store.
If no complete record has been written into the store,
the operation will return an empty record, rather than block.

.IP "\fB\-l\fP
Read the last value from the store.
This is the default behavior of \fIsgsh-readval\fP.
The operation will block until the store's server (\fIsgsh-writeval\fP)
determines that it has read the last record
by detecting an end-of-file condition on its standard input.

.IP "\fB\-n\fP
Do not retry a failed connection to the store.
By default \fIsgsh-readval\fP will try to establish a connection to the
store every one second.
This behavior is designed to avoid failures due to race conditions between write stores
that are started asynchronously (in the background) and subsequent read
operations from them.

.IP "\fB\-q\fP
Ask the write store (the corresponding \fIsgsh-writeval\fP process)
to terminate its operation.
No value is read.

.IP "\fB\-s\fP \fIpath\fP"
This mandatory option must be used to specify the path of the Unix-domain socket
\fIsgsh-readval\fP will connect to communicate with the store.
This is specified as a normal Unix file path,
e.g. \fC/tmp/myvalue\fP.

.SH "SEE ALSO"
\fIsgsh\fP(1),
\fIsgsh-writeval\fP(1)

.SH AUTHOR
Diomidis Spinellis \(em <http://www.spinellis.gr>