lckdo.docbook

   1 <?xml version="1.0" encoding="utf-8"?>
   2
   3 <!--
   4
   5 Written by Michael Tokarev <mjt@tls.msk.ru>
   6 Public 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>