diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/lockf.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/lockf.3p | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/lockf.3p b/man-pages-posix-2013/man3p/lockf.3p new file mode 100644 index 0000000..870fb59 --- /dev/null +++ b/man-pages-posix-2013/man3p/lockf.3p @@ -0,0 +1,291 @@ +'\" et +.TH LOCKF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lockf +\(em record locking on files +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +int lockf(int \fIfildes\fP, int \fIfunction\fP, off_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIlockf\fR() +function shall lock sections of a file with advisory-mode locks. Calls +to +\fIlockf\fR() +from threads in other processes which attempt to lock the locked file +section shall either return an error value or block until the section +becomes unlocked. All the locks for a process are removed when the +process terminates. Record locking with +\fIlockf\fR() +shall be supported for regular files and may be supported for other +files. +.P +The +.IR fildes +argument is an open file descriptor. To establish a lock with this +function, the file descriptor shall be opened with write-only +permission (O_WRONLY) or with read/write permission (O_RDWR). +.P +The +.IR function +argument is a control value which specifies the action to be taken. The +permissible values for +.IR function +are defined in +.IR <unistd.h> +as follows: +.TS +box tab(!) center; +cB | cB +l | l. +Function!Description +_ +F_ULOCK!Unlock locked sections. +F_LOCK!Lock a section for exclusive use. +F_TLOCK!Test and lock a section for exclusive use. +F_TEST!Test a section for locks by other processes. +.TE +.P +F_TEST shall detect if a lock by another process is present on the +specified section. +.P +F_LOCK and F_TLOCK shall both lock a section of a file if the section +is available. +.P +F_ULOCK shall remove locks from a section of the file. +.P +The +.IR size +argument is the number of contiguous bytes to be locked or unlocked. +The section to be locked or unlocked starts at the current offset in +the file and extends forward for a positive size or backward for a +negative size (the preceding bytes up to but not including the current +offset). If +.IR size +is 0, the section from the current offset through the largest possible +file offset shall be locked (that is, from the current offset through +the present or any future end-of-file). An area need not be allocated +to the file to be locked because locks may exist past the end-of-file. +.P +The sections locked with F_LOCK or F_TLOCK may, in whole or in part, +contain or be contained by a previously locked section for the same +process. When this occurs, or if adjacent locked sections would occur, +the sections shall be combined into a single locked section. If the +request would cause the number of locks to exceed a system-imposed +limit, the request shall fail. +.P +F_LOCK and F_TLOCK requests differ only by the action taken if the +section is not available. F_LOCK shall block the calling thread until +the section is available. F_TLOCK shall cause the function to fail if +the section is already locked by another process. +.P +File locks shall be released on first close by the locking process of +any file descriptor for the file. +.P +F_ULOCK requests may release (wholly or in part) one or more locked +sections controlled by the process. Locked sections shall be unlocked +starting at the current file offset through +.IR size +bytes or to the end-of-file if +.IR size +is (\fBoff_t\fR)0. When all of a locked section is not released (that +is, when the beginning or end of the area to be unlocked falls within a +locked section), the remaining portions of that section shall remain +locked by the process. Releasing the center portion of a locked section +shall cause the remaining locked beginning and end portions to become two +separate locked sections. If the request would cause the number of +locks in the system to exceed a system-imposed limit, the request +shall fail. +.P +A potential for deadlock occurs if the threads of a process controlling +a locked section are blocked by accessing a locked section of +another process. If the system detects that deadlock would occur, +\fIlockf\fR() +shall fail with an +.BR [EDEADLK] +error. +.P +The interaction between +\fIfcntl\fR() +and +\fIlockf\fR() +locks is unspecified. +.P +Blocking on a section shall be interrupted by any signal. +.P +An F_ULOCK request in which +.IR size +is non-zero and the offset of the last byte of the requested section is +the maximum value for an object of type +.BR off_t , +when the process has an existing lock in which +.IR size +is 0 and which includes the last byte of the requested section, shall be +treated as a request to unlock from the start of the requested section +with a size equal to 0. Otherwise, an F_ULOCK request shall attempt to +unlock only the requested section. +.P +Attempting to lock a section of a file that is associated with a +buffered stream produces unspecified results. +.SH "RETURN VALUE" +Upon successful completion, +\fIlockf\fR() +shall return 0. Otherwise, it shall return \(mi1, set +.IR errno +to indicate an error, and existing locks shall not be changed. +.SH ERRORS +The +\fIlockf\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor; or +.IR function +is F_LOCK or F_TLOCK and +.IR fildes +is not a valid file descriptor open for writing. +.TP +.BR EACCES " or " EAGAIN +.br +The +.IR function +argument is F_TLOCK or F_TEST and the section is already locked by +another process. +.TP +.BR EDEADLK +The +.IR function +argument is F_LOCK and a deadlock is detected. +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR EINVAL +The +.IR function +argument is not one of F_LOCK, F_TLOCK, F_TEST, or F_ULOCK; or +.IR size +plus the current file offset is less than 0. +.TP +.BR EOVERFLOW +The offset of the first, or if +.IR size +is not 0 then the last, byte in the requested section cannot be +represented correctly in an object of type +.BR off_t . +.P +The +\fIlockf\fR() +function may fail if: +.TP +.BR EAGAIN +The +.IR function +argument is F_LOCK or F_TLOCK and the file is mapped with +\fImmap\fR(). +.TP +.BR EDEADLK " or " ENOLCK +.br +The +.IR function +argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request would cause +the number of locks to exceed a system-imposed limit. +.TP +.BR EOPNOTSUPP " or " EINVAL +.br +The implementation does not support the locking of files of the type +indicated by the +.IR fildes +argument. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Locking a Portion of a File" +.P +In the following example, a file named +.BR /home/cnd/mod1 +is being modified. Other processes that use locking are prevented from +changing it during this process. Only the first 10\|000 bytes are +locked, and the lock call fails if another process has any part of this +area locked already. +.sp +.RS 4 +.nf +\fB +#include <fcntl.h> +#include <unistd.h> +.P +int fildes; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = lockf(fildes, F_TLOCK, (off_t)10000); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Record-locking should not be used in combination with the +\fIfopen\fR(), +\fIfread\fR(), +\fIfwrite\fR(), +and other +.IR stdio +functions. Instead, the more primitive, non-buffered functions (such as +\fIopen\fR()) +should be used. Unexpected results may occur in processes that do +buffering in the user address space. The process may later read/write +data which is/was locked. The +.IR stdio +functions are the most common source of unexpected buffering. +.P +The +\fIalarm\fR() +function may be used to provide a timeout facility in applications +requiring it. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB<unistd.h>\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |