* The following bugs are resolved with this release:
- 6804, 9894, 12994, 13347, 13651, 14308, 14770, 15119, 15132, 15347, 15514,
- 15698, 15804, 15894, 15946, 16002, 16064, 16095, 16198, 16284, 16287,
- 16315, 16348, 16349, 16354, 16357, 16362, 16447, 16516, 16532, 16539,
- 16545, 16561, 16562, 16564, 16574, 16599, 16600, 16609, 16610, 16611,
- 16613, 16619, 16623, 16629, 16632, 16634, 16639, 16642, 16648, 16649,
- 16670, 16674, 16677, 16680, 16681, 16683, 16689, 16695, 16701, 16706,
- 16707, 16712, 16713, 16714, 16724, 16731, 16739, 16740, 16743, 16754,
- 16758, 16759, 16760, 16770, 16786, 16789, 16791, 16796, 16799, 16800,
- 16815, 16823, 16824, 16831, 16838, 16849, 16854, 16876, 16877, 16878,
- 16882, 16885, 16888, 16890, 16912, 16915, 16916, 16917, 16918, 16922,
- 16927, 16928, 16932, 16943, 16958, 16965, 16966, 16967, 16977, 16978,
- 16984, 16990, 16996, 17009, 17022, 17031, 17042, 17048, 17050, 17058,
- 17061, 17062, 17069, 17075, 17078, 17079, 17084, 17086, 17088, 17092,
- 17097, 17125, 17135, 17137, 17150, 17153.
+ 6804, 9894, 12994, 13347, 13651, 14308, 14770, 15119, 15132, 15347,
+ 15514, 15698, 15804, 15894, 15946, 16002, 16064, 16095, 16198, 16284,
+ 16287, 16315, 16348, 16349, 16354, 16357, 16362, 16447, 16516, 16532,
+ 16539, 16545, 16561, 16562, 16564, 16574, 16599, 16600, 16609, 16610,
+ 16611, 16613, 16619, 16623, 16629, 16632, 16634, 16639, 16642, 16648,
+ 16649, 16670, 16674, 16677, 16680, 16681, 16683, 16689, 16695, 16701,
+ 16706, 16707, 16712, 16713, 16714, 16724, 16731, 16739, 16740, 16743,
+ 16754, 16758, 16759, 16760, 16770, 16786, 16789, 16791, 16796, 16799,
+ 16800, 16815, 16823, 16824, 16831, 16838, 16839, 16849, 16854, 16876,
+ 16877, 16878, 16882, 16885, 16888, 16890, 16912, 16915, 16916, 16917,
+ 16918, 16922, 16927, 16928, 16932, 16943, 16958, 16965, 16966, 16967,
+ 16977, 16978, 16984, 16990, 16996, 17009, 17022, 17031, 17042, 17048,
+ 17050, 17058, 17061, 17062, 17069, 17075, 17078, 17079, 17084, 17086,
+ 17088, 17092, 17097, 17125, 17135, 17137, 17150, 17153.
+
+* Support for file description locks is added to systems running the
+ Linux kernel. The standard file locking interfaces are extended to
+ operate on file descriptions, not file descriptors, via the use of
+ F_OFD_GETLK, F_OFD_SETLK, and F_OFD_SETLKW. File description locks
+ are associated with an open file instead of a process.
* Optimized strchr implementation for AArch64. Contributed by ARM Ltd.
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.
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}.
@item F_SETLKW
Like @code{F_SETLK}, but wait for completion. @xref{File Locks}.
+@item F_OFD_GETLK
+Test an open file description lock. @xref{Open File Description Locks}.
+Specific to Linux.
+
+@item F_OFD_SETLK
+Set or clear an open file description lock. @xref{Open File Description Locks}.
+Specific to Linux.
+
+@item F_OFD_SETLKW
+Like @code{F_OFD_SETLK}, but block until lock is acquired.
+@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}.
@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 file description instead of the process. @xref{Open File Description Locks}.
+
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
@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
@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.
+
+Using @code{fcntl} to apply an 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 open file @emph{description} (an
+instance of an open file, usually created by a call to @code{open}) and
+an open file @emph{descriptor}, which is a numeric value that refers to the
+open file description. The locks described here are associated with the
+open file @emph{description} and not the open file @emph{descriptor}.
+
+Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file
+descriptor does not give you a new open file description, but rather copies a
+reference to an existing open file description and assigns it 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 open file description. Depending on the range and type of lock
+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 @code{command} values are also declared in the header file
+@file{fcntl.h}. To use them, the macro @code{_GNU_SOURCE} must be
+defined prior to including any header file.
+
+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 an
+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 the lock is not associated with a process.
+
+When the same @code{struct flock} is reused as an argument to a
+@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
+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 is written to
+@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 are set to
+@code{SEEK_SET} and the @code{l_start} and @code{l_len} fields are set
+to identify 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
+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 open file already has a lock on any part of the
+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 command does not wait for other tasks
+to release locks. If @code{fcntl} succeeds, it returns @math{0}.
+
+The following @code{errno} error conditions are defined for this
+command:
+
+@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
+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 open file description.
+
+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 that locks
+are inadvertently 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 it would be
+subject to data corruption 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.
+
+Proper error handling has been omitted in the following program for
+brevity.
+
+@smallexample
+@include ofdlocks.c.texi
+@end smallexample
+
+This example creates three threads each of which loops five times,
+appending to the file. Access to the file is serialized via open file
+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 written by others.
+
@node Interrupt Input
@section Interrupt-Driven Input
projects / external / glibc.git / commitdiff