fcntl-linux.h: add new definitions and manual updates for open file description locks
RFC PATCH 1/1 fcntl-linux.h: add new definitions and manual updates for open file description locks
(I haven't yet sent the patch to rename these to Linus, but here's a
new draft version of the glibc header/manual updates for open file description locks. Please speak up if you see any issues or object to the new name.)
Open file description locks have been merged into the Linux kernel for v3.15. Add the appropriate command-value definitions and an update to the manual that describes their usage.
ChangeLog:
2014-04-23 Jeff Layton <[email protected]>
[BZ#16839]
* manual/llio.texi: add section about open file description locks
* sysdeps/unix/sysv/linux/bits/fcntl-linux.h:
(F_OFD_GETLK, F_OFD_SETLK, F_OFD_SETLKW): New macros.
--- manual/examples/ofdlocks.c | 75 +++++++++ manual/llio.texi | 237 ++++++++++++++++++++++++++++- sysdeps/unix/sysv/linux/bits/fcntl-linux.h | 17 +++ 3 files changed, 326 insertions(+), 3 deletions(-) create mode 100644 manual/examples/ofdlocks.c
manual/examples/ofdlocks.c new file +75 -0
@@ -0,0 +1,75 @@ +/* Open File Description Locks Usage Example +Copyright (C) 1991-2014 Free Software Foundation, Inc. + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, if not, see <http://www.gnu.org/licenses/>. +*/ + +#define _GNU_SOURCE +#include <stdio.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <unistd.h> +#include <fcntl.h> +#include <pthread.h> + +#define FILENAME "/tmp/foo" +#define NUM_THREADS 3 +#define ITERATIONS 5 + +void * +thread_start (void *arg) +{ +int i, fd, len; +long tid = (long )arg; +char buf[256 ]; +struct flock lck = { + .l_whence =SEEK_SET , + .l_start =0 , + .l_len =1 , + }; + + fd =open ("/tmp/foo" ,O_RDWR |O_CREAT ,0666 ); + +for (i =0 ; i <ITERATIONS ; i++) { + lck.l_type =F_WRLCK ; +fcntl (fd,F_OFD_SETLKW , &lck); + + len =sprintf (buf,"%d: tid=%ld fd=%d\n" , i, tid, fd); + +lseek (fd,0 ,SEEK_END ); +write (fd, buf, len); +fsync (fd); + + lck.l_type =F_UNLCK ; +fcntl (fd,F_OFD_SETLK , &lck); + +usleep (1 ); + } +pthread_exit (NULL ); +} + +int +main (int argc,char **argv) +{ +long i; +pthread_t threads[NUM_THREADS ]; + +truncate (FILENAME ,0 ); + +for (i =0 ; i <NUM_THREADS ; i++) +pthread_create (&threads[i],NULL , thread_start, (void *)i); + +pthread_exit (NULL ); +return 0 ; +}
manual/llio.texi +234 -3
276 lines not on this page · raw message
sysdeps/unix/sysv/linux/bits/fcntl-linux.h +17 -0
@@ -117,6 +117,23 @@# define F_SETLKW64 14/* Set record locking info (blocking). */ #endif +/* open file description locks. + +Usually record locks held by a process are released on *any* close and are +not inherited across a fork. + +These cmd values will set locks that conflict with process-associated record +locks, but are "owned" by the opened file description, not the process. +This means that they are inherited across fork or clone with CLONE_FILES +like BSD (flock) locks, and they are only released automatically when the +last reference to the the file description against which they were acquired +is put. */ +#if __USE_GNU +# define F_OFD_GETLK 36 +# define F_OFD_SETLK 37 +# define F_OFD_SETLKW 38 +#endif +#ifdef __USE_LARGEFILE64# define O_LARGEFILE __O_LARGEFILE#endif
Signature · 1 line
1.9.0
Hi Jeff,
Comments below.
Quoted 36 lines · Jeff Layton
(I haven't yet sent the patch to rename these to Linus, but here's a
new draft version of the glibc header/manual updates for open file description locks. Please speak up if you see any issues or object to the new name.)Open file description locks have been merged into the Linux kernel for v3.15. Add the appropriate command-value definitions and an update to the manual that describes their usage.
ChangeLog:
2014-04-23 Jeff Layton <[email protected]>
[BZ#16839]
* manual/llio.texi: add section about open file description locks*
sysdeps/unix/sysv/linux/bits/fcntl-linux.h:
(F_OFD_GETLK,F_OFD_SETLK,F_OFD_SETLKW): New macros.--- manual/examples/ofdlocks.c | 75 +++++++++ manual/llio.texi | 237 ++++++++++++++++++++++++++++- sysdeps/unix/sysv/linux/bits/fcntl-linux.h | 17 +++ 3 files changed, 326 insertions(+), 3 deletions(-) create mode 100644 manual/examples/ofdlocks.cmanual/examples/ofdlocks.c new file +5
-0@@ -0,0 +1,75 @@ +/* Open File Description Locks Usage Example +Copyright (C) 1991-2014 Free Software Foundation, Inc. + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License
manual/examples/ofdlocks.c line 15
Quoted 10 lines
manual/examples/ofdlocks.c new file +10
-0+ as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
s/if not, if not/if not/
Quoted 9 lines
manual/examples/ofdlocks.c new file +9
-0+*/ + +#define _GNU_SOURCE +#include <stdio.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <unistd.h> +#include <fcntl.h> +#include <pthread.h>
manual/examples/ofdlocks.c line 34
Quoted 10 lines
manual/examples/ofdlocks.c new file +10
-0+ +#define FILENAME "/tmp/foo" +#define NUM_THREADS 3 +#define ITERATIONS 5 + +void * +thread_start (void *arg) +{ +int i, fd, len; +long tid = (long )arg;
s/)/) /
manual/examples/ofdlocks.c line 42
Quoted 8 lines
manual/examples/ofdlocks.c new file +8
-0+char buf[256 ]; +struct flock lck = { + .l_whence =SEEK_SET , + .l_start =0 , + .l_len =1 , + }; + + fd =open ("/tmp/foo" ,O_RDWR |O_CREAT ,0666 );
s/|/ | /
manual/examples/ofdlocks.c line 44
Quoted 2 lines
manual/examples/ofdlocks.c new file +2
-0+ +for (i =0 ; i <ITERATIONS ; i++) {
I am no lover of the GNU coding style, but I suspect this program should be respecting it with respect to the brace style...
manual/examples/ofdlocks.c line 57
Quoted 13 lines
manual/examples/ofdlocks.c new file +13
-0+ lck.l_type =F_WRLCK ; +fcntl (fd,F_OFD_SETLKW , &lck); + + len =sprintf (buf,"%d: tid=%ld fd=%d\n" , i, tid, fd); + +lseek (fd,0 ,SEEK_END ); +write (fd, buf, len); +fsync (fd); + + lck.l_type =F_UNLCK ; +fcntl (fd,F_OFD_SETLK , &lck); + +usleep (1 );
I think the usleep() call needs to be either removed or explained.
manual/examples/ofdlocks.c line 66
Quoted 9 lines
manual/examples/ofdlocks.c new file +9
-0+ } +pthread_exit (NULL ); +} + +int +main (int argc,char **argv) +{ +long i; +pthread_t threads[NUM_THREADS ];
Why the large white space gap?
manual/examples/ofdlocks.c line 74
Quoted 8 lines
manual/examples/ofdlocks.c new file +8
-0+ +truncate (FILENAME ,0 ); + +for (i =0 ; i <NUM_THREADS ; i++) +pthread_create (&threads[i],NULL , thread_start, (void *)i); + +pthread_exit (NULL ); +return 0 ;
The "return 0" isn't needed.
Quoted 45 lines
manual/examples/ofdlocks.c new file +1
-0+}manual/llio.texi +17
-1@@ -57,6 +57,10 @@ directly.) flags associated with open files. * File Locks:: Fcntl commands for implementing file locking. +* Open File Description Locks:: Fcntl commands for implementing + open file description locking. +* Open File Description Locks Example:: An example of open file description lock + usage * Interrupt Input:: Getting an asynchronous signal when input arrives. * IOCTLs:: Generic I/O Control operations.@@ -2890,7 +2894,7 @@ Get flags associated with the open file. @xref{File Status Flags}. Set flags associated with the open file. @xref{File Status Flags}. @item F_GETLK -Get a file lock. @xref{File Locks}. +Test a file lock. @xref{File Locks}. @item F_SETLK Set or clear a file lock. @xref{File Locks}.@@ -2898,6 +2902,18 @@ Set or clear a file lock. @xref{File Locks}. @item F_SETLKW Like @code{F_SETLK}, but wait for completion. @xref{File Locks}. +@item F_OFD_GETLK +Test a open file description lock. @xref{Open File Description Locks}. +Specific to Linux. + +@item F_OFD_SETLK +Set or clear a file lock. @xref{Open File Description Locks}. +Specific to Linux. + +@item F_OFD_SETLKW +Like @code{F_OFD_SETLK}, but wait for completion. +@xref{Open File Description Locks}. Specific to Linux. + @item F_GETOWN Get process or process group ID to receive @code{SIGIO} signals. @xref{Interrupt Input}.
manual/llio.texi set_nonblock_flag (int desc, int value) · line 3597
Quoted 6 lines
manual/llio.texi +3
-0@@ -3576,6 +3592,10 @@ set_nonblock_flag (int desc, int value) @cindex file locks @cindex record locking +This section describes record locks that are associated with the process. +There is also a different type of record lock that is associated with the +open description instead of the process. @xref{Open File Description Locks}.
s/open/open file/
Quoted 31 lines
manual/llio.texi +12
-2+ The remaining @code{fcntl} commands are used to support @dfn{record locking}, which permits multiple cooperating programs to prevent each other from simultaneously accessing parts of a file in error-prone@@ -3641,7 +3661,10 @@ the file. @item pid_t l_pid This field is the process ID (@pxref{Process Creation Concepts}) of the process holding the lock. It is filled in by calling @code{fcntl} with -the @code{F_GETLK} command, but is ignored when making a lock. +the @code{F_GETLK} command, but is ignored when making a lock. If the +conflicting lock is an open file description lock +(@pxref{Open File Description Locks}), then this field will be set to +@math{-1}. @end table @end deftp@@ -3813,10 +3836,218 @@ that part of the file for writing. @c ??? This section could use an example program. -Remember that file locks are only a @emph{voluntary} protocol for +Remember that file locks are only an @emph{advisory} protocol for controlling access to a file. There is still potential for access to the file by programs that don't use the lock protocol. +@node Open File Description Locks +@section Open File Description Locks + +In contrast to process-associated record locks (@pxref{File Locks}), +open file description record locks are associated with an open file +description rather than a process.
manual/llio.texi that part of the file for writing. · line 3858
Quoted 10 lines
manual/llio.texi +10
-0+ +Using @code{fcntl} to apply a open file description lock on a region that +already has an existing open file description lock that was created via the +same file descriptor will never cause a lock conflict. + +Open file description locks are also inherited by child processes across +@code{fork}, or @code{clone} with @code{CLONE_FILES} set +(@pxref{Creating a Process}), along with the file descriptor. + +It is important to distinguish between the file @emph{description} (an
s/file/open file/
manual/llio.texi that part of the file for writing. · line 3861
Quoted 3 lines
manual/llio.texi +3
-0+instance of an open file, usually created by a call to @code{open}) and +a file @emph{descriptor}, which is a numeric value that refers to the +former. The locks described here are associated with the file
I'd s/former/open file description/ for clarity
and
s/file/open file/
manual/llio.texi that part of the file for writing. · line 3865
Quoted 4 lines
manual/llio.texi +4
-0+@emph{description} and not the file @emph{descriptor}. + +Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file +descriptor does not give you an entirely new file description , but
s/entirely//
(it's redundant, and possibly even confusing.)
manual/llio.texi that part of the file for writing. · line 3866
Quoted 1 line
manual/llio.texi +1
-0+rather copies a reference to an existing file description and assigns it
s/file/open file/
manual/llio.texi that part of the file for writing. · line 3870
Quoted 4 lines
manual/llio.texi +4
-0+to a new file descriptor. Thus, open file description locks set on a file +descriptor cloned by @code{dup} will never conflict with +open file description locks set on the original descriptor since they refer +to the same file description. Depending on the range and type of lock
s/file/open file/
manual/llio.texi that part of the file for writing. · line 3880
Quoted 10 lines
manual/llio.texi +10
-0+involved, the original lock may be modified by a @code{F_OFD_SETLK} or +@code{F_OFD_SETLKW} command in this situation however. + +Open file description locks always conflict with process-associated locks, +even if acquired by the same process or on the same open file +descriptor. + +Open file description locks use the same @code{struct flock} as +process-associated locks as an argument (@pxref{File Locks}) and the +macros for the cmd values are also declared in the header file
s/cmd/@code{command}/
manual/llio.texi that part of the file for writing. · line 3882
Quoted 2 lines
manual/llio.texi +2
-0+@file{fcntl.h}. To use them, the macro @code{_GNU_SOURCE} must be +defined prior to including @file{fcntl.h}.
s/prior to including @file{fcntl.h}/before including any header file/
(See http://man7.org/linux/man-pages/man7/feature_test_macros.7.html )
manual/llio.texi that part of the file for writing. · line 3886
Quoted 4 lines
manual/llio.texi +4
-0+ +In contrast to process-associated locks, any @code{struct flock} used as +an argument to open file description lock commands must have the @code{l_pid} +value set to @math{0}. Also, when returning information about a
s/s/an/
manual/llio.texi that part of the file for writing. · line 3891
Quoted 5 lines
manual/llio.texi +5
-0+open file description lock in a @code{F_GETLK} or @code{F_OFD_GETLK} request, +the @code{l_pid} field in @code{struct flock} will be set to @math{-1} +to indicate that a lock is not associated with a process. + +When the same struct flock is reused as an argument to a
s/struct flock/@code{struct flock}/
Quoted 8 lines
manual/llio.texi +8
-0+@code{F_OFD_SETLK} or @code{F_OFD_SETLKW} request after being used for an +@code{F_OFD_GETLK} request, it is necessary to inspect and reset the +@code{l_pid} field to @math{0}. + +@pindex fcntl.h. + +@deftypevr Macro int F_OFD_GETLK +This macro is used as the @var{command} argument to @code{fcntl}, to
manual/llio.texi that part of the file for writing. · line 3909
Quoted 10 lines
manual/llio.texi +10
-0+specify that it should get information about a lock. This command +requires a third argument of type @w{@code{struct flock *}} to be passed +to @code{fcntl}, so that the form of the call is: + +@smallexample +fcntl (@var{filedes}, F_OFD_GETLK, @var{lockp}) +@end smallexample + +If there is a lock already in place that would block the lock described +by the @var{lockp} argument, information about that lock overwrites
s/overwrites/is written to/
manual/llio.texi that part of the file for writing. · line 3921
Quoted 12 lines
manual/llio.texi +12
-0+@code{*@var{lockp}}. Existing locks are not reported if they are +compatible with making a new lock as specified. Thus, you should +specify a lock type of @code{F_WRLCK} if you want to find out about both +read and write locks, or @code{F_RDLCK} if you want to find out about +write locks only. + +There might be more than one lock affecting the region specified by the +@var{lockp} argument, but @code{fcntl} only returns information about +one of them. Which lock is returned in this situation is undefined. + +The @code{l_whence} member of the @var{lockp} structure is set to +@code{SEEK_SET} and the @code{l_start} and @code{l_len} fields set to identify
s/set/are set/
Quoted 23 lines
manual/llio.texi +23
-0+the locked region. + +If no conflicting lock exists, the only change to the @var{lockp} structure +is to update the @code{l_type} field to the value @code{F_UNLCK}. + +The normal return value from @code{fcntl} with this command is either @math{0} +on success or @math{-1}, which indicates an error. The following @code{errno} +error conditions are defined for this command: + +@table @code +@item EBADF +The @var{filedes} argument is invalid. + +@item EINVAL +Either the @var{lockp} argument doesn't specify valid lock information, +the operating system kernel doesn't support open file description locks, or the file +associated with @var{filedes} doesn't support locks. +@end table +@end deftypevr + +@comment fcntl.h +@comment POSIX.1 +@deftypevr Macro int F_OFD_SETLK
manual/llio.texi that part of the file for writing. · line 3954
Quoted 10 lines
manual/llio.texi +10
-0+This macro is used as the @var{command} argument to @code{fcntl}, to +specify that it should set or clear a lock. This command requires a +third argument of type @w{@code{struct flock *}} to be passed to +@code{fcntl}, so that the form of the call is: + +@smallexample +fcntl (@var{filedes}, F_OFD_SETLK, @var{lockp}) +@end smallexample + +If the opened file already has a lock on any part of the
s/opened/open/
manual/llio.texi that part of the file for writing. · line 3959
Quoted 5 lines
manual/llio.texi +5
-0+region, the old lock on that part is replaced with the new lock. You +can remove a lock by specifying a lock type of @code{F_UNLCK}. + +If the lock cannot be set, @code{fcntl} returns immediately with a value +of @math{-1}. This function does not wait for other tasks
s/function/command/
Quoted 48 lines
manual/llio.texi +48
-0+to release locks. If @code{fcntl} succeeds, it returns @math{0}. + +The following @code{errno} error conditions are defined for this +function: + +@table @code +@item EAGAIN +The lock cannot be set because it is blocked by an existing lock on the +file. + +@item EBADF +Either: the @var{filedes} argument is invalid; you requested a read lock +but the @var{filedes} is not open for read access; or, you requested a +write lock but the @var{filedes} is not open for write access. + +@item EINVAL +Either the @var{lockp} argument doesn't specify valid lock information, +the operating system kernel doesn't support open file description locks, or the +file associated with @var{filedes} doesn't support locks. + +@item ENOLCK +The system has run out of file lock resources; there are already too +many file locks in place. + +Well-designed file systems never report this error, because they have no +limitation on the number of locks. However, you must still take account +of the possibility of this error, as it could result from network access +to a file system on another machine. +@end table +@end deftypevr + +@comment fcntl.h +@comment POSIX.1 +@deftypevr Macro int F_OFD_SETLKW +This macro is used as the @var{command} argument to @code{fcntl}, to +specify that it should set or clear a lock. It is just like the +@code{F_OFD_SETLK} command, but causes the process to wait until the request +can be completed. + +This command requires a third argument of type @code{struct flock *}, as +for the @code{F_OFD_SETLK} command. + +The @code{fcntl} return values and errors are the same as for the +@code{F_OFD_SETLK} command, but these additional @code{errno} error conditions +are defined for this command: + +@table @code +@item EINTR
manual/llio.texi that part of the file for writing. · line 4017
Quoted 10 lines
manual/llio.texi +10
-0+The function was interrupted by a signal while it was waiting. +@xref{Interrupted Primitives}. + +@end table +@end deftypevr + +Open file description locks are useful in the same sorts of situations as +process-associated locks. They can also be used to synchronize file +access between threads within the same process by having each thread perform +its own @code{open} of the file, to obtain its own file description.
s/file/open file/
manual/llio.texi that part of the file for writing. · line 4020
Quoted 3 lines
manual/llio.texi +3
-0+ +Because they are only released automatically when the last reference to +file description is closed, open file description locks avoid the possibility
s/file description/open file description/
But, I'd rewrite the sentence a little:
Because open file description locks are automatically freed only upon closing the last file descriptor that refers to the open file description, this locking mechanism avoids the possibility...
manual/llio.texi that part of the file for writing. · line 4030
Quoted 10 lines
manual/llio.texi +10
-0+that locks are released due to a library routine opening and closing a file +without the application being aware. + +As with process-associated locks, open file description locks are advisory. + +@node Open File Description Locks Example +@section Open File Description Locks Example + +Here is an example of using open file description locks in a threaded program. If +this program used process-associated locks, then then it would be
s/then then/then/
manual/llio.texi that part of the file for writing. · line 4032
Quoted 2 lines
manual/llio.texi +2
-0+subject to data corruption due since multiple threads are running within +the same process.
That last piece is a biut confusing. How about
...because process-associated locks are shared by the threads inside a process, and thus cannot be used by one thread to lock out another thread in the same process.
manual/llio.texi that part of the file for writing.
Quoted 9 lines
Proper error handling has been omitted in the following
manual/llio.texi +8
-0+program for brevity. + +@smallexample +@include ofdlocks.c.texi +@end smallexample + +This example spawns three threads and has each do five iterations of +appending to a file.
Better:
This example creates three threads, each of which loops five times, appending to the file.
Quoted 1 line
Access to that file is serialized via open file
s/taht/the/
manual/llio.texi that part of the file for writing. · line 4048
Quoted 8 lines
manual/llio.texi +8
-0+description locks. If we compile and run the above program, we'll end up +with /tmp/foo that has 15 lines in it. + +If we, however, were to replace the @code{F_OFD_SETLK} and @code{F_OFD_SETLKW} +commands with their process-associated lock equivalents, the locking +essentially becomes a noop since it is all done within the context of +the same process. That leads to data corruption (typically manifested +as missing lines) as some threads race in and overwrite the data from
s/from/written by/
Quoted 34 lines
manual/llio.texi +2
-0+others. + @node Interrupt Input @section Interrupt-Driven Inputsysdeps/unix/sysv/linux/bits/fcntl-linux.h +17
-1@@ -117,6 +117,23 @@# define F_SETLKW64 14/* Set record locking info (blocking). */ #endif +/* open file description locks. + +Usually record locks held by a process are released on *any* close and are +not inherited across a fork. + +These cmd values will set locks that conflict with process-associated record +locks, but are "owned" by the opened file description, not the process. +This means that they are inherited across fork or clone with CLONE_FILES +like BSD (flock) locks, and they are only released automatically when the +last reference to the the file description against which they were acquired +is put. */ +#if __USE_GNU +# define F_OFD_GETLK 36 +# define F_OFD_SETLK 37 +# define F_OFD_SETLKW 38 +#endif +#ifdef __USE_LARGEFILE64# define O_LARGEFILE __O_LARGEFILE#endif --
Quoted 2 lines
1.9.0
Cheers,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
@@ -2890,7 +2894,7 @@ Get flags associated with the open file. @xref{File Status Flags}.
Set flags associated with the open file. @xref{File Status Flags}.
@item F_GETLK
-Get a file lock. @xref{File Locks}.
+Test a file lock. @xref{File Locks}.
F_GETLK does get the (first) lock which blocks; it doesn't test for it. "Retrieves information about the first blocking lock ..." or something might be better than the original
@@ -2898,6 +2902,18 @@ Set or clear a file lock. @xref{File Locks}.
@item F_SETLKW
Like @code{F_SETLK}, but wait for completion. @xref{File Locks}.
+@item F_OFD_GETLK
+Test a open file description lock. @xref{Open File Description Locks}. +Specific to Linux.
Likewise. You infact write that it does get the lock information later in the document wrt. F_OFD_GETLK.
Quoted 15 lines · On Wed, 23 Apr 2014 11:09:51 -0400 [email protected] (Alfred M. Szmidt) wrote:
@@ -2890,7 +2894,7 @@ Get flags associated with the open file. @xref{File Status Flags}.
Set flags associated with the open file. @xref{File Status Flags}.@item
F_GETLK
-Get a file lock. @xref{File Locks}.
+Test a file lock. @xref{File Locks}.
F_GETLKdoes get the (first) lock which blocks; it doesn't test for it. "Retrieves information about the first blocking lock ..." or something might be better than the original@@ -2898,6 +2902,18 @@ Set or clear a file lock. @xref{File Locks}.
@itemF_SETLKW
Like @code{F_SETLK}, but wait for completion. @xref{File Locks}.
Quoted 6 lines
+@item
F_OFD_GETLK
+Test a open file description lock. @xref{Open File Description Locks}. +Specific to Linux.Likewise. You infact write that it does get the lock information later in the document wrt.
F_OFD_GETLK.
Sorry, I disagree here...GETLK is really a misnomer, IMO. TESTLK would have been a better name.
It's a way to test whether a particular lock can be applied, and to return information about a conflicting lock if it can't. If, for instance there is no conflicting lock, then you don't "get" any lock information back (l_type just gets reset to F_UNLCK).
Signature · 1 line
Jeff Layton <[email protected]>
Quoted 2 lines
Likewise. You infact write that it does get the lock information later in the document wrt.
F_OFD_GETLK.
Sorry, I disagree here...GETLK is really a misnomer, IMO. TESTLK would have been a better name.
GETLK are used is to "get the first lock".
It's a way to test whether a particular lock can be applied, and to return information about a conflicting lock if it can't. If, for instance there is no conflicting lock, then you don't "get" any lock information back (l_type just gets reset to F_UNLCK).
While I kinda see your point, it isn't what GETLK does; it really does get you information about the first lock -- you're not testing anything. It is also the terminology used in the POSIX standard.
Quoted 5 lines · Alfred M. Szmidt
Quoted 2 lines
Likewise. You infact write that it does get the lock information later in the document wrt.
F_OFD_GETLK.Sorry, I disagree here...GETLK is really a misnomer, IMO. TESTLK would have been a better name.
I'm inclined to agree.
Quoted 10 lines
GETLK are used is to "get the first lock".
It's a way to test whether a particular lock can be applied, and to return information about a conflicting lock if it can't. If, for instance there is no conflicting lock, then you don't "get" any lock information back (
l_typejust gets reset toF_UNLCK).While I kinda see your point, it isn't what GETLK does; it really does get you information about the first lock -- you're not testing anything. It is also the terminology used in the POSIX standard.
The POSIX wording is a little confused. For example, what does "first" mean in this context? F_GETLK returns information about one (arbitrarily selected) lock that blocks a lock you would like to place. So, I'm inclined to agree with Jeff -- this really is a "test" (or "can I lock it") operation.
Of course, the operation has no reliable use: by the time it returns the information might already be out of date. I suspect that it was designed to solve the problem: "My F_GETLK operation failed. Who's blocking me?"
Cheers,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 8 lines · On Wed, 23 Apr 2014 15:00:06 -0400 [email protected] (Alfred M. Szmidt) wrote:
Quoted 2 lines
Likewise. You infact write that it does get the lock information later in the document wrt.
F_OFD_GETLK.Sorry, I disagree here...GETLK is really a misnomer, IMO. TESTLK would have been a better name.
GETLK are used is to "get the first lock".
Quoted 8 lines
It's a way to test whether a particular lock can be applied, and to return information about a conflicting lock if it can't. If, for instance there is no conflicting lock, then you don't "get" any lock information back (
l_typejust gets reset toF_UNLCK).While I kinda see your point, it isn't what GETLK does; it really does get you information about the first lock -- you're not testing anything. It is also the terminology used in the POSIX standard.
You *are* testing a lock.
For instance, a process has locked bytes 0-5 for read in the file. I then submit a F_GETLK request from another process and set:
l_type = F_WRLCK
l_start = 7
l_len = 1...this range does not overlap with the original range, and so no lock will be returned even though one is being held on the file. In order to determine whether it should return information about a lock it has to first _test_ whether it conflicts with the information in the struct flock that was passed down.
Similarly, if the struct flock I submit to the F_GETLK request has this:
l_type = F_RDLCK
l_start = 0
l_len = 1
...then I also will not get any information about a lock back. The information in the lock request does not conflict with the one being held on the file (because they are both read locks).
If F_GETLK were just "getting" a lock, then there would be no test involved, but that's not how this works. F_GETLK has to test and see whether there is a conflicting lock before it can return anything.
If all you're objecting to is the change in verbiage on those two pieces, then I'll back that part out in the interest of wrapping this up.
I still think I'm correct though ;)
Signature · 1 line
Jeff Layton <[email protected]>