summaryrefslogtreecommitdiff
path: root/lckdo.docbook
blob: effe84d29436f6749b7b0614b6a59c700f287ccf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
<?xml version="1.0" encoding="utf-8"?>

<!--

Written by Michael Tokarev <mjt@tls.msk.ru>
Public domain.

-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd"
[]>

<refentry>
	<refentryinfo>
		<address>
			<email>mjt@tls.msk.ru</email>
		</address>
		<author>
			<firstname>Michael</firstname>
			<surname>Tokarev</surname>
		</author>
		<date>2007-08-15</date>
	</refentryinfo>

	<refmeta>
		<refentrytitle>lckdo</refentrytitle>
		<manvolnum>1</manvolnum>
	</refmeta>

	<refnamediv>
		<refname>lckdo</refname> 
		<refpurpose>run a program with a lock held</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>lckdo</command>
			<arg>options</arg>
			<arg choice="req">lockfile</arg>
			<arg choice="req">program</arg>
			<arg>arguments</arg>
		</cmdsynopsis>
	</refsynopsisdiv>
	
	<refsect1>
		<title>DESCRIPTION</title>
		
		<para><command>lckdo</command> runs a program with a lock
		held, in order to prevent multiple processes from running in
		parallel. Use just like <command>nice</command> or
		<command>nohup</command>.</para>

		<para>Now that util-linux contains a similar command
		named <command>flock</command>, lckdo is deprecated,
		and will be removed from some future version of moreutils.
		</para>

	</refsect1>
	
	<refsect1>
		<title>OPTIONS</title>
		
		<variablelist>
		
		<varlistentry>
			<term><option>-w</option></term>
			<listitem>
				<para>If the lock is already held by another process,
				wait for it to complete instead of failing
				immediately.</para>
			</listitem>
		</varlistentry>
		
		<varlistentry>
			<term><option>-W {sec}</option></term>
			<listitem>
				<para>The same as -w but wait not more than sec
				seconds.</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><option>-e</option></term>
			<listitem>
				<para>Execute the program directly without forking and
				waiting (keeps an extra file descriptor open).</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><option>-E {nnn}</option></term>
			<listitem>
				<para>Set the file descriptor number to keep open when
				exec()ing (implies -e).</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><option>-n</option></term>
			<listitem>
				<para>Do not create the lock file if it does not
				exist.</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><option>-q</option></term>
			<listitem>
				<para>Produce no output if lock is already held.</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><option>-s</option></term>
			<listitem>
				<para>Lock in shared (read) mode.</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><option>-x</option></term>
			<listitem>
				<para>Lock in exclusive (write) mode (default).</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><option>-t</option></term>
			<listitem>
				<para>Test for lock existence.</para>
			</listitem>
		</varlistentry>

		</variablelist>
		
	</refsect1>
	
	<refsect1>
		<title>EXIT STATUS</title>

        <para>If the lock was successfully acquired, the return value is that
        of the program invoked by <command>lckdo</command>. If the lock
        couldn't be acquired, EX_TEMPFAIL is returned. If there was a problem
        opening/creating or locking the lock file, EX_CANTCREAT or EX_OSERR
        will be returned.</para>
		
	</refsect1>
	
	<refsect1>
		<title>AUTHOR</title>
		<para>
			Michael Tokarev
		</para>
	</refsect1>

</refentry>