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 "file:///usr/share/xml/docbook/schema/dtd/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         </refmeta>
  30
  31         <refnamediv>
  32                 <refname>lckdo</refname>
  33                 <refpurpose>run a program with a lock held</refpurpose>
  34         </refnamediv>
  35
  36         <refsynopsisdiv>
  37                 <cmdsynopsis>
  38                         <command>lckdo</command>
  39                         <arg>options</arg>
  40                         <arg choice="req">lockfile</arg>
  41                         <arg choice="req">program</arg>
  42                         <arg>arguments</arg>
  43                 </cmdsynopsis>
  44         </refsynopsisdiv>
  45
  46         <refsect1>
  47                 <title>DESCRIPTION</title>
  48
  49                 <para><command>lckdo</command> runs a program with a lock
  50                 held, in order to prevent multiple processes from running in
  51                 parallel. Use just like <command>nice</command> or
  52                 <command>nohup</command>.</para>
  53
  54                 <para>Now that util-linux contains a similar command
  55                 named <command>flock</command>, lckdo is deprecated,
  56                 and will be removed from some future version of moreutils.
  57                 </para>
  58
  59         </refsect1>
  60
  61         <refsect1>
  62                 <title>OPTIONS</title>
  63
  64                 <variablelist>
  65
  66                 <varlistentry>
  67                         <term><option>-w</option></term>
  68                         <listitem>
  69                                 <para>If the lock is already held by another process,
  70                                 wait for it to complete instead of failing
  71                                 immediately.</para>
  72                         </listitem>
  73                 </varlistentry>
  74
  75                 <varlistentry>
  76                         <term><option>-W {sec}</option></term>
  77                         <listitem>
  78                                 <para>The same as -w but wait not more than sec
  79                                 seconds.</para>
  80                         </listitem>
  81                 </varlistentry>
  82
  83                 <varlistentry>
  84                         <term><option>-e</option></term>
  85                         <listitem>
  86                                 <para>Execute the program directly without forking and
  87                                 waiting (keeps an extra file descriptor open).</para>
  88                         </listitem>
  89                 </varlistentry>
  90
  91                 <varlistentry>
  92                         <term><option>-E {nnn}</option></term>
  93                         <listitem>
  94                                 <para>Set the file descriptor number to keep open when
  95                                 exec()ing (implies -e).</para>
  96                         </listitem>
  97                 </varlistentry>
  98
  99                 <varlistentry>
 100                         <term><option>-n</option></term>
 101                         <listitem>
 102                                 <para>Do not create the lock file if it does not
 103                                 exist.</para>
 104                         </listitem>
 105                 </varlistentry>
 106
 107                 <varlistentry>
 108                         <term><option>-q</option></term>
 109                         <listitem>
 110                                 <para>Produce no output if lock is already held.</para>
 111                         </listitem>
 112                 </varlistentry>
 113
 114                 <varlistentry>
 115                         <term><option>-s</option></term>
 116                         <listitem>
 117                                 <para>Lock in shared (read) mode.</para>
 118                         </listitem>
 119                 </varlistentry>
 120
 121                 <varlistentry>
 122                         <term><option>-x</option></term>
 123                         <listitem>
 124                                 <para>Lock in exclusive (write) mode (default).</para>
 125                         </listitem>
 126                 </varlistentry>
 127
 128                 <varlistentry>
 129                         <term><option>-t</option></term>
 130                         <listitem>
 131                                 <para>Test for lock existence.</para>
 132                         </listitem>
 133                 </varlistentry>
 134
 135                 </variablelist>
 136
 137         </refsect1>
 138
 139         <refsect1>
 140                 <title>EXIT STATUS</title>
 141
 142         <para>If the lock was successfully acquired, the return value is that
 143         of the program invoked by <command>lckdo</command>. If the lock
 144         couldn't be acquired, EX_TEMPFAIL is returned. If there was a problem
 145         opening/creating or locking the lock file, EX_CANTCREAT or EX_OSERR
 146         will be returned.</para>
 147
 148         </refsect1>
 149
 150         <refsect1>
 151                 <title>AUTHOR</title>
 152                 <para>
 153                         Michael Tokarev
 154                 </para>
 155         </refsect1>
 156
 157 </refentry>