logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

lockf.3p (8769B)


  1. '\" et
  2. .TH LOCKF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. lockf
  12. \(em record locking on files
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int lockf(int \fIfildes\fP, int \fIfunction\fP, off_t \fIsize\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIlockf\fR()
  23. function shall lock sections of a file with advisory-mode locks. Calls
  24. to
  25. \fIlockf\fR()
  26. from threads in other processes which attempt to lock the locked file
  27. section shall either return an error value or block until the section
  28. becomes unlocked. All the locks for a process are removed when the
  29. process terminates. Record locking with
  30. \fIlockf\fR()
  31. shall be supported for regular files and may be supported for other
  32. files.
  33. .P
  34. The
  35. .IR fildes
  36. argument is an open file descriptor. To establish a lock with this
  37. function, the file descriptor shall be opened with write-only
  38. permission (O_WRONLY) or with read/write permission (O_RDWR).
  39. .P
  40. The
  41. .IR function
  42. argument is a control value which specifies the action to be taken. The
  43. permissible values for
  44. .IR function
  45. are defined in
  46. .IR <unistd.h>
  47. as follows:
  48. .TS
  49. box tab(!) center;
  50. cB | cB
  51. l | l.
  52. Function!Description
  53. _
  54. F_ULOCK!Unlock locked sections.
  55. F_LOCK!Lock a section for exclusive use.
  56. F_TLOCK!Test and lock a section for exclusive use.
  57. F_TEST!Test a section for locks by other processes.
  58. .TE
  59. .P
  60. F_TEST shall detect if a lock by another process is present on the
  61. specified section.
  62. .P
  63. F_LOCK and F_TLOCK shall both lock a section of a file if the section
  64. is available.
  65. .P
  66. F_ULOCK shall remove locks from a section of the file.
  67. .P
  68. The
  69. .IR size
  70. argument is the number of contiguous bytes to be locked or unlocked.
  71. The section to be locked or unlocked starts at the current offset in
  72. the file and extends forward for a positive size or backward for a
  73. negative size (the preceding bytes up to but not including the current
  74. offset). If
  75. .IR size
  76. is 0, the section from the current offset through the largest possible
  77. file offset shall be locked (that is, from the current offset through
  78. the present or any future end-of-file). An area need not be allocated
  79. to the file to be locked because locks may exist past the end-of-file.
  80. .P
  81. The sections locked with F_LOCK or F_TLOCK may, in whole or in part,
  82. contain or be contained by a previously locked section for the same
  83. process. When this occurs, or if adjacent locked sections would occur,
  84. the sections shall be combined into a single locked section. If the
  85. request would cause the number of locks to exceed a system-imposed
  86. limit, the request shall fail.
  87. .P
  88. F_LOCK and F_TLOCK requests differ only by the action taken if the
  89. section is not available. F_LOCK shall block the calling thread until
  90. the section is available. F_TLOCK shall cause the function to fail if
  91. the section is already locked by another process.
  92. .P
  93. File locks shall be released on first close by the locking process of
  94. any file descriptor for the file.
  95. .P
  96. F_ULOCK requests may release (wholly or in part) one or more locked
  97. sections controlled by the process. Locked sections shall be unlocked
  98. starting at the current file offset through
  99. .IR size
  100. bytes or to the end-of-file if
  101. .IR size
  102. is (\fBoff_t\fR)0. When all of a locked section is not released (that
  103. is, when the beginning or end of the area to be unlocked falls within a
  104. locked section), the remaining portions of that section shall remain
  105. locked by the process. Releasing the center portion of a locked section
  106. shall cause the remaining locked beginning and end portions to become two
  107. separate locked sections. If the request would cause the number of
  108. locks in the system to exceed a system-imposed limit, the request
  109. shall fail.
  110. .P
  111. A potential for deadlock occurs if the threads of a process controlling
  112. a locked section are blocked by accessing a locked section of
  113. another process. If the system detects that deadlock would occur,
  114. \fIlockf\fR()
  115. shall fail with an
  116. .BR [EDEADLK]
  117. error.
  118. .P
  119. The interaction between
  120. \fIfcntl\fR()
  121. and
  122. \fIlockf\fR()
  123. locks is unspecified.
  124. .P
  125. Blocking on a section shall be interrupted by any signal.
  126. .P
  127. An F_ULOCK request in which
  128. .IR size
  129. is non-zero and the offset of the last byte of the requested section is
  130. the maximum value for an object of type
  131. .BR off_t ,
  132. when the process has an existing lock in which
  133. .IR size
  134. is 0 and which includes the last byte of the requested section, shall be
  135. treated as a request to unlock from the start of the requested section
  136. with a size equal to 0. Otherwise, an F_ULOCK request shall attempt to
  137. unlock only the requested section.
  138. .P
  139. Attempting to lock a section of a file that is associated with a
  140. buffered stream produces unspecified results.
  141. .SH "RETURN VALUE"
  142. Upon successful completion,
  143. \fIlockf\fR()
  144. shall return 0. Otherwise, it shall return \-1, set
  145. .IR errno
  146. to indicate an error, and existing locks shall not be changed.
  147. .SH ERRORS
  148. The
  149. \fIlockf\fR()
  150. function shall fail if:
  151. .TP
  152. .BR EBADF
  153. The
  154. .IR fildes
  155. argument is not a valid open file descriptor; or
  156. .IR function
  157. is F_LOCK or F_TLOCK and
  158. .IR fildes
  159. is not a valid file descriptor open for writing.
  160. .TP
  161. .BR EACCES " or " EAGAIN
  162. .br
  163. The
  164. .IR function
  165. argument is F_TLOCK or F_TEST and the section is already locked by
  166. another process.
  167. .TP
  168. .BR EDEADLK
  169. The
  170. .IR function
  171. argument is F_LOCK and a deadlock is detected.
  172. .TP
  173. .BR EINTR
  174. A signal was caught during execution of the function.
  175. .TP
  176. .BR EINVAL
  177. The
  178. .IR function
  179. argument is not one of F_LOCK, F_TLOCK, F_TEST, or F_ULOCK; or
  180. .IR size
  181. plus the current file offset is less than 0.
  182. .TP
  183. .BR EOVERFLOW
  184. The offset of the first, or if
  185. .IR size
  186. is not 0 then the last, byte in the requested section cannot be
  187. represented correctly in an object of type
  188. .BR off_t .
  189. .P
  190. The
  191. \fIlockf\fR()
  192. function may fail if:
  193. .TP
  194. .BR EAGAIN
  195. The
  196. .IR function
  197. argument is F_LOCK or F_TLOCK and the file is mapped with
  198. \fImmap\fR().
  199. .TP
  200. .BR EDEADLK " or " ENOLCK
  201. .br
  202. The
  203. .IR function
  204. argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request would cause
  205. the number of locks to exceed a system-imposed limit.
  206. .TP
  207. .BR EOPNOTSUPP " or " EINVAL
  208. .br
  209. The implementation does not support the locking of files of the type
  210. indicated by the
  211. .IR fildes
  212. argument.
  213. .LP
  214. .IR "The following sections are informative."
  215. .SH EXAMPLES
  216. .SS "Locking a Portion of a File"
  217. .P
  218. In the following example, a file named
  219. .BR /home/cnd/mod1
  220. is being modified. Other processes that use locking are prevented from
  221. changing it during this process. Only the first 10\|000 bytes are
  222. locked, and the lock call fails if another process has any part of this
  223. area locked already.
  224. .sp
  225. .RS 4
  226. .nf
  227. #include <fcntl.h>
  228. #include <unistd.h>
  229. .P
  230. int fildes;
  231. int status;
  232. \&...
  233. fildes = open("/home/cnd/mod1", O_RDWR);
  234. status = lockf(fildes, F_TLOCK, (off_t)10000);
  235. .fi
  236. .P
  237. .RE
  238. .SH "APPLICATION USAGE"
  239. Record-locking should not be used in combination with the
  240. \fIfopen\fR(),
  241. \fIfread\fR(),
  242. \fIfwrite\fR(),
  243. and other
  244. .IR stdio
  245. functions. Instead, the more primitive, non-buffered functions (such as
  246. \fIopen\fR())
  247. should be used. Unexpected results may occur in processes that do
  248. buffering in the user address space. The process may later read/write
  249. data which is/was locked. The
  250. .IR stdio
  251. functions are the most common source of unexpected buffering.
  252. .P
  253. The
  254. \fIalarm\fR()
  255. function may be used to provide a timeout facility in applications
  256. requiring it.
  257. .SH RATIONALE
  258. None.
  259. .SH "FUTURE DIRECTIONS"
  260. None.
  261. .SH "SEE ALSO"
  262. .IR "\fIalarm\fR\^(\|)",
  263. .IR "\fIchmod\fR\^(\|)",
  264. .IR "\fIclose\fR\^(\|)",
  265. .IR "\fIcreat\fR\^(\|)",
  266. .IR "\fIfcntl\fR\^(\|)",
  267. .IR "\fIfopen\fR\^(\|)",
  268. .IR "\fImmap\fR\^(\|)",
  269. .IR "\fIopen\fR\^(\|)",
  270. .IR "\fIread\fR\^(\|)",
  271. .IR "\fIwrite\fR\^(\|)"
  272. .P
  273. The Base Definitions volume of POSIX.1\(hy2017,
  274. .IR "\fB<unistd.h>\fP"
  275. .\"
  276. .SH COPYRIGHT
  277. Portions of this text are reprinted and reproduced in electronic form
  278. from IEEE Std 1003.1-2017, Standard for Information Technology
  279. -- Portable Operating System Interface (POSIX), The Open Group Base
  280. Specifications Issue 7, 2018 Edition,
  281. Copyright (C) 2018 by the Institute of
  282. Electrical and Electronics Engineers, Inc and The Open Group.
  283. In the event of any discrepancy between this version and the original IEEE and
  284. The Open Group Standard, the original IEEE and The Open Group Standard
  285. is the referee document. The original Standard can be obtained online at
  286. http://www.opengroup.org/unix/online.html .
  287. .PP
  288. Any typographical or formatting errors that appear
  289. in this page are most likely
  290. to have been introduced during the conversion of the source files to
  291. man page format. To report such errors, see
  292. https://www.kernel.org/doc/man-pages/reporting_bugs.html .