1<?xml version="1.0" encoding="utf-8"?>
2
3<!--
4
5Written by Michael Tokarev <mjt@tls.msk.ru>
6Public domain.
7
8-->
9
10<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
11"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
12[]>
13
14<refentry>
15	<refentryinfo>
16		<address>
17			<email>mjt@tls.msk.ru</email>
18		</address>
19		<author>
20			<firstname>Michael</firstname>
21			<surname>Tokarev</surname>
22		</author>
23		<date>2007-08-15</date>
24	</refentryinfo>
25
26	<refmeta>
27		<refentrytitle>lckdo</refentrytitle>
28		<manvolnum>1</manvolnum>
29		<refmiscinfo class="manual">moreutils</refmiscinfo>
30		<refmiscinfo class="source">moreutils</refmiscinfo>
31	</refmeta>
32
33	<refnamediv>
34		<refname>lckdo</refname>
35		<refpurpose>run a program with a lock held</refpurpose>
36	</refnamediv>
37
38	<refsynopsisdiv>
39		<cmdsynopsis>
40			<command>lckdo</command>
41			<arg>options</arg>
42			<arg choice="req">lockfile</arg>
43			<arg choice="req">program</arg>
44			<arg>arguments</arg>
45		</cmdsynopsis>
46	</refsynopsisdiv>
47
48	<refsect1>
49		<title>DESCRIPTION</title>
50
51		<para><command>lckdo</command> runs a program with a lock
52		held, in order to prevent multiple processes from running in
53		parallel. Use just like <command>nice</command> or
54		<command>nohup</command>.</para>
55
56		<para>Now that util-linux contains a similar command
57		named <command>flock</command>, lckdo is deprecated,
58		and will be removed from some future version of moreutils.
59		</para>
60
61	</refsect1>
62
63	<refsect1>
64		<title>OPTIONS</title>
65
66		<variablelist>
67
68		<varlistentry>
69			<term><option>-w</option></term>
70			<listitem>
71				<para>If the lock is already held by another process,
72				wait for it to complete instead of failing
73				immediately.</para>
74			</listitem>
75		</varlistentry>
76
77		<varlistentry>
78			<term><option>-W {sec}</option></term>
79			<listitem>
80				<para>The same as -w but wait not more than sec
81				seconds.</para>
82			</listitem>
83		</varlistentry>
84
85		<varlistentry>
86			<term><option>-e</option></term>
87			<listitem>
88				<para>Execute the program directly without forking and
89				waiting (keeps an extra file descriptor open).</para>
90			</listitem>
91		</varlistentry>
92
93		<varlistentry>
94			<term><option>-E {nnn}</option></term>
95			<listitem>
96				<para>Set the file descriptor number to keep open when
97				exec()ing (implies -e).</para>
98			</listitem>
99		</varlistentry>
100
101		<varlistentry>
102			<term><option>-n</option></term>
103			<listitem>
104				<para>Do not create the lock file if it does not
105				exist.</para>
106			</listitem>
107		</varlistentry>
108
109		<varlistentry>
110			<term><option>-q</option></term>
111			<listitem>
112				<para>Produce no output if lock is already held.</para>
113			</listitem>
114		</varlistentry>
115
116		<varlistentry>
117			<term><option>-s</option></term>
118			<listitem>
119				<para>Lock in shared (read) mode.</para>
120			</listitem>
121		</varlistentry>
122
123		<varlistentry>
124			<term><option>-x</option></term>
125			<listitem>
126				<para>Lock in exclusive (write) mode (default).</para>
127			</listitem>
128		</varlistentry>
129
130		<varlistentry>
131			<term><option>-t</option></term>
132			<listitem>
133				<para>Test for lock existence.</para>
134			</listitem>
135		</varlistentry>
136
137		</variablelist>
138
139	</refsect1>
140
141	<refsect1>
142		<title>EXIT STATUS</title>
143
144        <para>If the lock was successfully acquired, the return value is that
145        of the program invoked by <command>lckdo</command>. If the lock
146        couldn't be acquired, EX_TEMPFAIL is returned. If there was a problem
147        opening/creating or locking the lock file, EX_CANTCREAT or EX_OSERR
148        will be returned.</para>
149
150	</refsect1>
151
152	<refsect1>
153		<title>AUTHOR</title>
154		<para>
155			Michael Tokarev
156		</para>
157	</refsect1>
158
159</refentry>
160