1File::FcntlLock::Pure(3U)ser Contributed Perl DocumentatiFoinle::FcntlLock::Pure(3)
2
3
4

NAME

6       File::FcntlLock - File locking with fcntl(2)
7
8       This text also documents the following sub-packages:
9
10       File::FcntlLock::XS
11       File::FcntlLock::Pure
12       File::FcntlLock::Inline
13

SYNOPSIS

15         use File::FcntlLock;
16
17         my $fs = new File::FcntlLock;
18         $fs->l_type( F_RDLCK );
19         $fs->l_whence( SEEK_CUR );
20         $fs->l_start( 100 );
21         $fs->l_len( 123 );
22
23         open my $fh, '<', 'file_name' or die "Can't open file: $!\n";
24         $fs->lock( $fh, F_SETLK )
25             or print "Locking failed: " . $fs->error . "\n";
26         $fs->l_type( F_UNLCK );
27         $fs->lock( $fh, F_SETLK )
28             or print "Unlocking failed: " . $fs->error . "\n";
29

DESCRIPTION

31       File locking in Perl is usually done using the "flock" function.
32       Unfortunately, this only allows locks on whole files and is often
33       implemented in terms of the flock(2) system function which has some
34       shortcomings (especially concerning locks on remotely mounted file
35       systems) and slightly different behaviour than fcntl(2).
36
37       Using this module file locking via fcntl(2) can be done (obviously,
38       this restricts the use of the module to systems that have a fcntl(2)
39       system call). Before a file (or parts of a file) can be locked, an
40       object simulating a flock structure, containing information in a binary
41       format to be passed to fcntl(2) for locking requests, must be created
42       and its properties set. Afterwards, by calling the lock() method a lock
43       can be set and removed or it can be determined if and which process
44       currently holds the lock.
45
46       File::FcntlLock (or its alias File::FcntlLock::XS) uses a shared
47       library, build during installation, to call the fcntl(2) system
48       function directly.  If this is unsuitable there are two alternatives,
49       File::FcntlLock::Pure and File::FcntlLock::Inline. Both call the Perl
50       "fcntl" function instead and use Perl code to assemble and disassemble
51       the structure. For this at some time the (system-dependent) binary
52       layout of the flock structure must have been determined via a program
53       written in C. The difference between File::FcntlLock::Pure and
54       File::FcntlLock::Inline is that for the former this happened when the
55       package is installed while for the latter it is done each time the
56       package is loaded (e.g., with "use"). Thus, for File::FcntlLock::Inline
57       to work a C compiler must be available. There are some minor
58       differences in the functionality and the behaviour on passing the
59       method for locking invalid arguments to be described below.
60
61   Creating objects
62       "new()"
63           To create a new object, representing a flock structure, call new():
64
65             $fs = new File::FcntlLock;
66
67           The object has a number of properties, reflecting the members of
68           the flock structure to be passed to fcntl(2) (see below). Per
69           default on object creation the l_type property is set to "F_RDLCK",
70           l_whence to "SEEK_SET", and both l_start and l_len to 0, i.e., the
71           settings for a read lock on the whole file.
72
73           These defaults can be overruled by passing the new() method a set
74           of key-value pairs to initialize the objects properties, e.g. use
75
76             $fs = new File::FcntlLock( l_type   => F_WRLCK,
77                                        l_whence => SEEK_SET,
78                                        l_start  => 0,
79                                        l_len    => 100 );
80
81           if you intend to obtain a write lock for the first 100 bytes of a
82           file.
83
84   Object properties
85       Once the object simulating the flock structure has been created the
86       following methods allow to query and, in most cases, to also modify its
87       properties.
88
89       "l_type()"
90           If called without an argument the method returns the current
91           setting of the lock type, otherwise the lock type is set to the
92           argument's value which must be either "F_RDLCK", "F_WRLCK" or
93           "F_UNLCK" (for read lock, write lock or unlock).
94
95       "l_whence()"
96           This method sets, when called with an argument, the l_whence
97           property of the flock object, determining if the l_start value is
98           relative to the start of the file, to the current position in the
99           file or to the end of the file. These values are "SEEK_SET",
100           "SEEK_CUR" and "SEEK_END" (also see the man page for lseek(2)).  If
101           called with no argument the current value of the property is
102           returned.
103
104       "l_start()"
105           Queries or sets the start position (offset) of the lock in the file
106           according to the mode selected by the l_whence member. See also the
107           man page for lseek(2).
108
109       "l_len()"
110           Queries or sets the length of the region (in bytes) in the file to
111           be locked. A value of 0 is interpreted to mean a lock, starting at
112           "l_start", to the end of the file. E.g., a lock obtained with
113           l_whence set to "SEEK_SET" and both l_start and l_len set to 0
114           locks the complete file.
115
116           According to SUSv3 support for negative values for l_len are
117           permitted, resulting in a lock ranging from "l_start+l_len" up to
118           and including "l_start-1". But not all systems support negative
119           values for l_len and will return an error when you try to obtain
120           such a lock, so please read the fcntl(2) man page of the system
121           carefully for details.
122
123       "l_pid()"
124           If a call of the lock() method with "F_GETLK" indicates that
125           another process is holding the lock (in which case the l_type
126           property will be either "F_WRLCK" or "F_RDLCK") a call of the
127           l_pid() method returns the PID of the process holding the lock.
128           This method does not accept any arguments.
129
130   Locking
131       After having set up the object representing a flock structure one can
132       then try to obtain a lock, release it or determine the current holder
133       of the lock by invoking the lock() method:
134
135       "lock()"
136           This method expects two arguments. The first one is a file handle
137           (or typeglob). File::FcntlLock, and thus File::FcntlLock::XS (but
138           neither File::FcntlLock::Pure nor File::FcntlLock::Inline), also
139           accepts a "raw" integer file descriptor. The second argument is a
140           flag indicating the action to be taken. So call it as in
141
142             $fs->lock( $fh, F_SETLK );
143
144           There are three values that can be used as the second argument:
145
146           "F_SETLK"
147               With "F_SETLK" the lock() method tries to obtain a lock (when
148               l_type is set to either "F_WRLCK" or "F_RDLCK") or releases it
149               (if l_type is set to "F_UNLCK"). If an attempt is made to
150               obtain a lock but a lock is already being held by some other
151               process the method returns "undef" and "errno" is set to
152               "EACCESS" or "EAGAIN" (please see the the man page for fcntl(2)
153               for more details).
154
155           "F_SETLKW"
156               is similar to "F_SETLK", but instead of returning an error if
157               the lock can't be obtained immediately it puts the calling
158               process to sleep, i.e., it blocks, until the lock is obtained
159               at some later time. If a signal is received while waiting for
160               the lock the method returns "undef" and "errno" is set to
161               "EINTR".
162
163           "F_GETLK"
164               With "F_GETLK" the lock() method determines if and which
165               process currently is holding the lock.  If there's no other
166               lock the l_type property will be set to "F_UNLCK". Otherwise
167               the flock structure object is set to the values that would
168               prevent us from obtaining a lock. There may be several
169               processes that keep us from getting a lock, including some that
170               themselves are blocked waiting to obtain a lock. "F_GETLK" will
171               only make details of one of these processes visible, and one
172               has no control over which process this is.
173
174           On success the lock() method returns the string "0 but true", i.e.,
175           a value that is true in boolean but 0 in numeric context. If the
176           method fails (as indicated by an "undef" return value) you can
177           either immediately evaluate the error number (using $!, $ERRNO or
178           $OS_ERROR) or check for it via the methods discussed below at some
179           later time.
180
181   Error handling
182       There are minor differences between File::FcntlLock on the one hand and
183       File::FcntlLock::Pure and File::FcntlLock::Inline on the other, due to
184       the first calling the system function fcntl(2) directly while the
185       latter two invoke the Perl "fcntl" function. Perl's "fcntl" function
186       already returns a Perl error on some types of invalid arguments. In
187       contrast File::FcntlLock passes them on to the fcntl(2) system call and
188       then returns the systems response to the caller.
189
190       There are three methods for obtaining information about the reason the
191       a call of the lock() method failed:
192
193       "lock_errno()"
194           Returns the "errno" error number from the latest call of lock().
195           If the last call did not result in an error "undef" is returned.
196
197       "error()"
198           Returns a short description of the error that happened during the
199           latest call of lock(). Please take the messages with a grain of
200           salt, they represent what SUSv3 (IEEE 1003.1-2001) and the Linux,
201           TRUE64, OpenBSD3 and Solaris8 man pages tell what the error numbers
202           mean. There could be differences (and additional error numbers) on
203           other systems. If there was no error the method returns "undef".
204
205       "system_error()"
206           While the error() method tries to return a string with some direct
207           relevance to the locking operation (i.e., "File or segment already
208           locked by other process(es)" instead of "Permission denied") this
209           method returns the "normal" system error message associated with
210           "errno". The method returns "undef" if there was no error.
211
212   EXPORT
213       The package exports the following constants:
214
215       F_GETLK F_SETLK F_SETLKW
216       F_RDLCK F_WRLCK F_UNLCK
217       SEEK_SET SEEK_CUR SEEK_END
218

INCOMPATIBILITIES

220       Obviously, this module requires that there's a fcntl(2) system call.
221       Note also that under certain circumstances the File::FcntlLock::Pure
222       and File::FcntlLock::Inline modules may not have been installed. This
223       happens on 32-bit systems that use 64-bit integers in their flock
224       structure but where the installed Perl version doesn't support the 'q'
225       format for its "pack" and "unpack" functions.
226

CREDITS

228       Thanks to Mark Jason Dominus and Benjamin Goldberg for helpful
229       discussions, code examples and encouragement. Glenn Herteg pointed out
230       several problems and also helped improve the documentation. Julian
231       Moreno Patino helped correcting the documentation and pointed out
232       problems arising on GNU Hurd which seems to have only very rudimentary
233       support for locking with fcntl(2). Niko Tyni and Guillem Jover
234       encouraged and helped with implementing alternatives to an XS-only
235       approach which hopefully will make the module more useful under certain
236       circumstances.
237

AUTHOR

239       Jens Thoms Toerring <jt@toerring.de>
240

SEE ALSO

242       perl(1), fcntl(2), lseek(2).
243

LICENSE

245       This library is free software. You can redistribute it and/or modify it
246       under the same terms as Perl itself.
247
248
249
250perl v5.32.0                      2020-07-28          File::FcntlLock::Pure(3)
Impressum