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

fcntl.3p (24213B)


  1. '\" et
  2. .TH FCNTL "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. fcntl
  12. \(em file control
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <fcntl.h>
  17. .P
  18. int fcntl(int \fIfildes\fP, int \fIcmd\fP, ...);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIfcntl\fR()
  23. function shall perform the operations described below on open files. The
  24. .IR fildes
  25. argument is a file descriptor.
  26. .P
  27. The available values for
  28. .IR cmd
  29. are defined in
  30. .IR <fcntl.h>
  31. and are as follows:
  32. .IP F_DUPFD 14
  33. Return a new file descriptor which shall be allocated as described in
  34. .IR "Section 2.14" ", " "File Descriptor Allocation",
  35. except that it shall be the lowest numbered available file
  36. descriptor greater than or equal to the third argument,
  37. .IR arg ,
  38. taken as an integer of type
  39. .BR int .
  40. The new file descriptor shall refer to the same open file description as
  41. the original file descriptor, and shall share any locks. The FD_CLOEXEC
  42. flag associated with the new file descriptor shall be cleared to keep
  43. the file open across calls to one of the
  44. .IR exec
  45. functions.
  46. .IP F_DUPFD_CLOEXEC 14
  47. .br
  48. Like F_DUPFD, but the FD_CLOEXEC flag associated with the new file
  49. descriptor shall be set.
  50. .IP F_GETFD 14
  51. Get the file descriptor flags defined in
  52. .IR <fcntl.h>
  53. that are associated with the file descriptor
  54. .IR fildes .
  55. File descriptor flags are associated with a single file descriptor and
  56. do not affect other file descriptors that refer to the same file.
  57. .IP F_SETFD 14
  58. Set the file descriptor flags defined in
  59. .IR <fcntl.h> ,
  60. that are associated with
  61. .IR fildes ,
  62. to the third argument,
  63. .IR arg ,
  64. taken as type
  65. .BR int .
  66. If the FD_CLOEXEC flag in the third argument
  67. is 0, the file descriptor shall remain open across the
  68. .IR exec
  69. functions; otherwise, the file descriptor shall be closed upon
  70. successful execution of one of the
  71. .IR exec
  72. functions.
  73. .IP F_GETFL 14
  74. Get the file status flags and file access modes, defined in
  75. .IR <fcntl.h> ,
  76. for the file description associated with
  77. .IR fildes .
  78. The file access modes can be extracted from the return value using the
  79. mask O_ACCMODE, which is defined in
  80. .IR <fcntl.h> .
  81. File status flags and file access modes are associated with the file
  82. description and do not affect other file descriptors that refer to the
  83. same file with different open file descriptions. The flags returned may
  84. include non-standard file status flags which the application did not
  85. set, provided that these additional flags do not alter the behavior of
  86. a conforming application.
  87. .IP F_SETFL 14
  88. Set the file status flags, defined in
  89. .IR <fcntl.h> ,
  90. for the file description associated with
  91. .IR fildes
  92. from the corresponding bits in the third argument,
  93. .IR arg ,
  94. taken as type
  95. .BR int .
  96. Bits corresponding to the file access mode and the file creation
  97. flags, as defined in
  98. .IR <fcntl.h> ,
  99. that are set in
  100. .IR arg
  101. shall be ignored. If any bits in
  102. .IR arg
  103. other than those mentioned here are changed by the application, the
  104. result is unspecified. If
  105. .IR fildes
  106. does not support non-blocking operations, it is unspecified whether the
  107. O_NONBLOCK flag will be ignored.
  108. .IP F_GETOWN 14
  109. If
  110. .IR fildes
  111. refers to a socket, get the process ID or process group ID specified to
  112. receive SIGURG signals when out-of-band data is available. Positive
  113. values shall indicate a process ID; negative values, other than \-1,
  114. shall indicate a process group ID; the value zero shall indicate
  115. that no SIGURG signals are to be sent. If
  116. .IR fildes
  117. does not refer to a socket, the results are unspecified.
  118. .IP F_SETOWN 14
  119. If
  120. .IR fildes
  121. refers to a socket, set the process ID or process group ID specified to
  122. receive SIGURG signals when out-of-band data is available, using the
  123. value of the third argument,
  124. .IR arg ,
  125. taken as type
  126. .BR int .
  127. Positive values shall indicate a process ID; negative values,
  128. other than \-1, shall indicate a process group ID; the value zero
  129. shall indicate that no SIGURG signals are to be sent. Each time a
  130. SIGURG signal is sent to the specified process or process group,
  131. permission checks equivalent to those performed by
  132. \fIkill\fR()
  133. shall be performed, as if
  134. \fIkill\fR()
  135. were called by a process with the same real user ID, effective
  136. user ID, and privileges that the process calling
  137. \fIfcntl\fR()
  138. has at the time of the call; if the
  139. \fIkill\fR()
  140. call would fail, no signal shall be sent. These permission checks may
  141. also be performed by the
  142. \fIfcntl\fR()
  143. call. If the process specified by
  144. .IR arg
  145. later terminates, or the process group specified by
  146. .IR arg
  147. later becomes empty, while still being specified to receive
  148. SIGURG signals when out-of-band data is available from
  149. .IR fildes ,
  150. then no signals shall be sent to any subsequently created process
  151. that has the same process ID or process group ID, regardless of
  152. permission; it is unspecified whether this is achieved by the
  153. equivalent of a
  154. .IR fcntl ( fildes ", F_SETOWN, 0)"
  155. call at the time the process terminates or is waited for or the
  156. process group becomes empty, or by other means. If
  157. .IR fildes
  158. does not refer to a socket, the results are unspecified.
  159. .P
  160. The following values for
  161. .IR cmd
  162. are available for advisory record locking. Record locking shall be
  163. supported for regular files, and may be supported for other files.
  164. .IP F_GETLK 14
  165. Get any lock which blocks the lock description pointed to by the
  166. third argument,
  167. .IR arg ,
  168. taken as a pointer to type
  169. .BR "struct flock" ,
  170. defined in
  171. .IR <fcntl.h> .
  172. The information retrieved shall overwrite the information passed to
  173. \fIfcntl\fR()
  174. in the structure
  175. .BR flock .
  176. If no lock is found that would prevent this lock from being created,
  177. then the structure shall be left unchanged except for the lock type
  178. which shall be set to F_UNLCK.
  179. .IP F_SETLK 14
  180. Set or clear a file segment lock according to the lock description
  181. pointed to by the third argument,
  182. .IR arg ,
  183. taken as a pointer to type
  184. .BR "struct flock" ,
  185. defined in
  186. .IR <fcntl.h> .
  187. F_SETLK can establish shared (or read) locks (F_RDLCK) or
  188. exclusive (or write) locks (F_WRLCK), as well as to remove either type
  189. of lock (F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in
  190. .IR <fcntl.h> .
  191. If a shared or exclusive lock cannot be set,
  192. \fIfcntl\fR()
  193. shall return immediately with a return value of \-1.
  194. .IP F_SETLKW 14
  195. This command shall be equivalent to F_SETLK except that if a shared or
  196. exclusive lock is blocked by other locks, the thread shall wait until
  197. the request can be satisfied. If a signal that is to be caught is
  198. received while
  199. \fIfcntl\fR()
  200. is waiting for a region,
  201. \fIfcntl\fR()
  202. shall be interrupted. Upon return from the signal handler,
  203. \fIfcntl\fR()
  204. shall return \-1 with
  205. .IR errno
  206. set to
  207. .BR [EINTR] ,
  208. and the lock operation shall not be done.
  209. .P
  210. Additional implementation-defined values for
  211. .IR cmd
  212. may be defined in
  213. .IR <fcntl.h> .
  214. Their names shall start with F_.
  215. .P
  216. When a shared lock is set on a segment of a file, other processes shall
  217. be able to set shared locks on that segment or a portion of it. A
  218. shared lock prevents any other process from setting an exclusive lock
  219. on any portion of the protected area. A request for a shared lock
  220. shall fail if the file descriptor was not opened with read access.
  221. .P
  222. An exclusive lock shall prevent any other process from setting a shared
  223. lock or an exclusive lock on any portion of the protected area. A
  224. request for an exclusive lock shall fail if the file descriptor was not
  225. opened with write access.
  226. .P
  227. The structure
  228. .BR flock
  229. describes the type (\c
  230. .IR l_type ),
  231. starting offset (\c
  232. .IR l_whence ),
  233. relative offset (\c
  234. .IR l_start ),
  235. size (\c
  236. .IR l_len ),
  237. and process ID (\c
  238. .IR l_pid )
  239. of the segment of the file to be affected.
  240. .P
  241. The value of
  242. .IR l_whence
  243. is SEEK_SET, SEEK_CUR, or SEEK_END,
  244. to indicate that the relative offset
  245. .IR l_start
  246. bytes shall be measured from the start of the file, current position,
  247. or end of the file, respectively. The value of
  248. .IR l_len
  249. is the number of consecutive bytes to be locked. The value of
  250. .IR l_len
  251. may be negative (where the definition of
  252. .BR off_t
  253. permits negative values of
  254. .IR l_len ).
  255. The
  256. .IR l_pid
  257. field is only used with F_GETLK to return the process ID of the process
  258. holding a blocking lock. After a successful F_GETLK request, when a
  259. blocking lock is found, the values returned in the
  260. .BR flock
  261. structure shall be as follows:
  262. .IP "\fIl_type\fP" 10
  263. Type of blocking lock found.
  264. .IP "\fIl_whence\fP" 10
  265. SEEK_SET.
  266. .IP "\fIl_start\fP" 10
  267. Start of the blocking lock.
  268. .IP "\fIl_len\fP" 10
  269. Length of the blocking lock.
  270. .IP "\fIl_pid\fP" 10
  271. Process ID of the process that holds the blocking lock.
  272. .P
  273. If the command is F_SETLKW and the process must wait for another
  274. process to release a lock, then the range of bytes to be locked shall
  275. be determined before the
  276. \fIfcntl\fR()
  277. function blocks. If the file size or file descriptor seek offset change
  278. while
  279. \fIfcntl\fR()
  280. is blocked, this shall not affect the range of bytes locked.
  281. .P
  282. If
  283. .IR l_len
  284. is positive, the area affected shall start at
  285. .IR l_start
  286. and end at
  287. .IR l_start +\c
  288. .IR l_len \-1.
  289. If
  290. .IR l_len
  291. is negative, the area affected shall start at
  292. .IR l_start +\c
  293. .IR l_len
  294. and end at
  295. .IR l_start \-1.
  296. Locks may start and extend beyond the current end of a file, but shall
  297. not extend before the beginning of the file. A lock shall be set to
  298. extend to the largest possible value of the file offset for that file
  299. by setting
  300. .IR l_len
  301. to 0. If such a lock also has
  302. .IR l_start
  303. set to 0 and
  304. .IR l_whence
  305. is set to SEEK_SET, the whole file shall be locked.
  306. .P
  307. There shall be at most one type of lock set for each byte in the file.
  308. Before a successful return from an F_SETLK or an F_SETLKW request when
  309. the calling process has previously existing locks on bytes in the
  310. region specified by the request, the previous lock type for each byte
  311. in the specified region shall be replaced by the new lock type. As
  312. specified above under the descriptions of shared locks and exclusive
  313. locks, an F_SETLK or an F_SETLKW request (respectively) shall fail or
  314. block when another process has existing locks on bytes in the specified
  315. region and the type of any of those locks conflicts with the type
  316. specified in the request.
  317. .P
  318. All locks associated with a file for a given process shall be removed
  319. when a file descriptor for that file is closed by that process or the
  320. process holding that file descriptor terminates. Locks are not
  321. inherited by a child process.
  322. .P
  323. A potential for deadlock occurs if a process controlling a locked
  324. region is put to sleep by attempting to lock the locked region of
  325. another process. If the system detects that sleeping until a locked
  326. region is unlocked would cause a deadlock,
  327. \fIfcntl\fR()
  328. shall fail with an
  329. .BR [EDEADLK]
  330. error.
  331. .P
  332. An unlock (F_UNLCK) request in which
  333. .IR l_len
  334. is non-zero and the offset of the last byte of the requested segment is
  335. the maximum value for an object of type
  336. .BR off_t ,
  337. when the process has an existing lock in which
  338. .IR l_len
  339. is 0 and which includes the last byte of the requested segment, shall be
  340. treated as a request to unlock from the start of the requested segment
  341. with an
  342. .IR l_len
  343. equal to 0. Otherwise, an unlock (F_UNLCK) request shall attempt to
  344. unlock only the requested segment.
  345. .P
  346. When the file descriptor
  347. .IR fildes
  348. refers to a shared memory object, the behavior of
  349. \fIfcntl\fR()
  350. shall be the same as for a regular file except the effect of the
  351. following values for the argument
  352. .IR cmd
  353. shall be unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.
  354. .P
  355. If
  356. .IR fildes
  357. refers to a typed memory object, the result of the
  358. \fIfcntl\fR()
  359. function is unspecified.
  360. .SH "RETURN VALUE"
  361. Upon successful completion, the value returned shall depend on
  362. .IR cmd
  363. as follows:
  364. .IP F_DUPFD 12
  365. A new file descriptor.
  366. .IP F_DUPFD_CLOEXEC 12
  367. .br
  368. A new file descriptor.
  369. .IP F_GETFD 12
  370. Value of flags defined in
  371. .IR <fcntl.h> .
  372. The return value shall not be negative.
  373. .IP F_SETFD 12
  374. Value other than \-1.
  375. .IP F_GETFL 12
  376. Value of file status flags and access modes. The return value is not
  377. negative.
  378. .IP F_SETFL 12
  379. Value other than \-1.
  380. .IP F_GETLK 12
  381. Value other than \-1.
  382. .IP F_SETLK 12
  383. Value other than \-1.
  384. .IP F_SETLKW 12
  385. Value other than \-1.
  386. .IP F_GETOWN 12
  387. Value of the socket owner process or process group; this will not be
  388. \-1.
  389. .IP F_SETOWN 12
  390. Value other than \-1.
  391. .P
  392. Otherwise, \-1 shall be returned and
  393. .IR errno
  394. set to indicate the error.
  395. .SH ERRORS
  396. The
  397. \fIfcntl\fR()
  398. function shall fail if:
  399. .TP
  400. .BR EACCES " or " EAGAIN
  401. .br
  402. The
  403. .IR cmd
  404. argument is F_SETLK; the type of lock (\c
  405. .IR l_type )
  406. is a shared (F_RDLCK) or exclusive (F_WRLCK) lock and the segment of a
  407. file to be locked is already exclusive-locked by another process, or the
  408. type is an exclusive lock and some portion of the segment of a file to
  409. be locked is already shared-locked or exclusive-locked by another process.
  410. .TP
  411. .BR EBADF
  412. The
  413. .IR fildes
  414. argument is not a valid open file descriptor, or the argument
  415. .IR cmd
  416. is F_SETLK or F_SETLKW, the type of lock,
  417. .IR l_type ,
  418. is a shared lock (F_RDLCK), and
  419. .IR fildes
  420. is not a valid file descriptor open for reading, or the type of lock,
  421. .IR l_type ,
  422. is an exclusive lock (F_WRLCK), and
  423. .IR fildes
  424. is not a valid file descriptor open for writing.
  425. .TP
  426. .BR EINTR
  427. The
  428. .IR cmd
  429. argument is F_SETLKW and the function was interrupted by a signal.
  430. .TP
  431. .BR EINVAL
  432. The
  433. .IR cmd
  434. argument is invalid, or the
  435. .IR cmd
  436. argument is F_DUPFD or F_DUPFD_CLOEXEC and
  437. .IR arg
  438. is negative or greater than or equal to
  439. {OPEN_MAX},
  440. or the
  441. .IR cmd
  442. argument is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by
  443. .IR arg
  444. is not valid, or
  445. .IR fildes
  446. refers to a file that does not support locking.
  447. .TP
  448. .BR EMFILE
  449. The argument
  450. .IR cmd
  451. is F_DUPFD or F_DUPFD_CLOEXEC and all file descriptors available to
  452. the process are currently open, or no file descriptors greater than or
  453. equal to
  454. .IR arg
  455. are available.
  456. .TP
  457. .BR ENOLCK
  458. The argument
  459. .IR cmd
  460. is F_SETLK or F_SETLKW and satisfying the lock or unlock request would
  461. result in the number of locked regions in the system exceeding a
  462. system-imposed limit.
  463. .TP
  464. .BR EOVERFLOW
  465. One of the values to be returned cannot be represented correctly.
  466. .TP
  467. .BR EOVERFLOW
  468. The
  469. .IR cmd
  470. argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if
  471. .IR l_len
  472. is non-zero, the largest offset of any byte in the requested segment
  473. cannot be represented correctly in an object of type
  474. .BR off_t .
  475. .TP
  476. .BR ESRCH
  477. The
  478. .IR cmd
  479. argument is F_SETOWN and no process or process group can be found
  480. corresponding to that specified by
  481. .IR arg .
  482. .br
  483. .P
  484. The
  485. \fIfcntl\fR()
  486. function may fail if:
  487. .TP
  488. .BR EDEADLK
  489. The
  490. .IR cmd
  491. argument is F_SETLKW, the lock is blocked by a lock from another
  492. process, and putting the calling process to sleep to wait for that lock
  493. to become free would cause a deadlock.
  494. .TP
  495. .BR EINVAL
  496. The
  497. .IR cmd
  498. argument is F_SETOWN and the value of the argument is not valid as a
  499. process or process group identifier.
  500. .TP
  501. .BR EPERM
  502. The
  503. .IR cmd
  504. argument is F_SETOWN and the calling process does not have
  505. permission to send a SIGURG signal to any process specified by
  506. .IR arg .
  507. .LP
  508. .IR "The following sections are informative."
  509. .SH EXAMPLES
  510. .SS "Locking and Unlocking a File"
  511. .P
  512. The following example demonstrates how to place a lock on bytes 100 to
  513. 109 of a file and then later remove it. F_SETLK is used to perform a
  514. non-blocking lock request so that the process does not have to wait if
  515. an incompatible lock is held by another process; instead the process
  516. can take some other action.
  517. .sp
  518. .RS 4
  519. .nf
  520. #include <stdlib.h>
  521. #include <unistd.h>
  522. #include <fcntl.h>
  523. #include <errno.h>
  524. #include <stdio.h>
  525. .P
  526. int
  527. main(int argc, char *argv[])
  528. {
  529. int fd;
  530. struct flock fl;
  531. .P
  532. fd = open("testfile", O_RDWR);
  533. if (fd == -1)
  534. /* Handle error */;
  535. .P
  536. /* Make a non-blocking request to place a write lock
  537. on bytes 100-109 of testfile */
  538. .P
  539. fl.l_type = F_WRLCK;
  540. fl.l_whence = SEEK_SET;
  541. fl.l_start = 100;
  542. fl.l_len = 10;
  543. .P
  544. if (fcntl(fd, F_SETLK, &fl) == -1) {
  545. if (errno == EACCES || errno == EAGAIN) {
  546. printf("Already locked by another process\en");
  547. .P
  548. /* We cannot get the lock at the moment */
  549. .P
  550. } else {
  551. /* Handle unexpected error */;
  552. }
  553. } else { /* Lock was granted... */
  554. .P
  555. /* Perform I/O on bytes 100 to 109 of file */
  556. .P
  557. /* Unlock the locked bytes */
  558. .P
  559. fl.l_type = F_UNLCK;
  560. fl.l_whence = SEEK_SET;
  561. fl.l_start = 100;
  562. fl.l_len = 10;
  563. if (fcntl(fd, F_SETLK, &fl) == -1)
  564. /* Handle error */;
  565. }
  566. exit(EXIT_SUCCESS);
  567. } /* main */
  568. .fi
  569. .P
  570. .RE
  571. .SS "Setting the Close-on-Exec Flag"
  572. .P
  573. The following example demonstrates how to set the close-on-exec flag
  574. for the file descriptor
  575. .IR fd .
  576. .sp
  577. .RS 4
  578. .nf
  579. #include <unistd.h>
  580. #include <fcntl.h>
  581. \&...
  582. int flags;
  583. .P
  584. flags = fcntl(fd, F_GETFD);
  585. if (flags == -1)
  586. /* Handle error */;
  587. flags |= FD_CLOEXEC;
  588. if (fcntl(fd, F_SETFD, flags) == -1)
  589. /* Handle error */;"
  590. .fi
  591. .P
  592. .RE
  593. .SH "APPLICATION USAGE"
  594. The
  595. .IR arg
  596. values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag
  597. values to allow for future growth. Applications using these functions
  598. should do a read-modify-write operation on them, rather than assuming
  599. that only the values defined by this volume of POSIX.1\(hy2017 are valid. It is a common error to
  600. forget this, particularly in the case of F_SETFD. Some implementations
  601. set additional file status flags to advise the application of default
  602. behavior, even though the application did not request these flags.
  603. .P
  604. On systems which do not perform permission checks at the time of an
  605. \fIfcntl\fR()
  606. call with F_SETOWN, if the permission checks performed at the time
  607. the signal is sent disallow sending the signal to any process,
  608. the process that called
  609. \fIfcntl\fR()
  610. has no way of discovering that this has happened. A call to
  611. \fIkill\fR()
  612. with signal 0 can be used as a prior check of permissions, although
  613. this is no guarantee that permission will be granted at the time
  614. a signal is sent, since the target process(es) could change
  615. user IDs or privileges in the meantime.
  616. .SH RATIONALE
  617. The ellipsis in the SYNOPSIS is the syntax specified by the ISO\ C standard
  618. for a variable number of arguments. It is used because System V uses
  619. pointers for the implementation of file locking functions.
  620. .P
  621. This volume of POSIX.1\(hy2017 permits concurrent read and write access to file data using the
  622. \fIfcntl\fR()
  623. function; this is a change from the 1984 /usr/group standard and early proposals. Without
  624. concurrency controls, this feature may not be fully utilized without
  625. occasional loss of data.
  626. .P
  627. Data losses occur in several ways. One case occurs when several
  628. processes try to update the same record, without sequencing controls;
  629. several updates may occur in parallel and the last writer ``wins''.
  630. Another case is a bit-tree or other internal list-based database that
  631. is undergoing reorganization. Without exclusive use to the tree segment
  632. by the updating process, other reading processes chance getting lost in
  633. the database when the index blocks are split, condensed, inserted, or
  634. deleted. While
  635. \fIfcntl\fR()
  636. is useful for many applications, it is not intended to be overly
  637. general and does not handle the bit-tree example well.
  638. .P
  639. This facility is only required for regular files because it is not
  640. appropriate for many devices such as terminals and network
  641. connections.
  642. .P
  643. Since
  644. \fIfcntl\fR()
  645. works with ``any file descriptor associated with that file, however it
  646. is obtained'', the file descriptor may have been inherited through a
  647. \fIfork\fR()
  648. or
  649. .IR exec
  650. operation and thus may affect a file that another process also has
  651. open.
  652. .P
  653. The use of the open file description to identify what to lock requires
  654. extra calls and presents problems if several processes are sharing an
  655. open file description, but there are too many implementations of the
  656. existing mechanism for this volume of POSIX.1\(hy2017 to use different specifications.
  657. .P
  658. Another consequence of this model is that closing any file descriptor
  659. for a given file (whether or not it is the same open file description
  660. that created the lock) causes the locks on that file to be relinquished
  661. for that process. Equivalently, any close for any file/process pair
  662. relinquishes the locks owned on that file for that process. But note
  663. that while an open file description may be shared through
  664. \fIfork\fR(),
  665. locks are not inherited through
  666. \fIfork\fR().
  667. Yet locks may be inherited through one of the
  668. .IR exec
  669. functions.
  670. .P
  671. The identification of a machine in a network environment is outside
  672. the scope of this volume of POSIX.1\(hy2017. Thus, an
  673. .IR l_sysid
  674. member, such as found in System V, is not included in the locking
  675. structure.
  676. .P
  677. Changing of lock types can result in a previously locked region being
  678. split into smaller regions.
  679. .P
  680. Mandatory locking was a major feature of the 1984 /usr/group standard.
  681. .P
  682. For advisory file record locking to be effective, all processes that
  683. have access to a file must cooperate and use the advisory mechanism
  684. before doing I/O on the file. Enforcement-mode record locking is
  685. important when it cannot be assumed that all processes are cooperating.
  686. For example, if one user uses an editor to update a file at the same
  687. time that a second user executes another process that updates the same
  688. file and if only one of the two processes is using advisory locking,
  689. the processes are not cooperating. Enforcement-mode record locking
  690. would protect against accidental collisions.
  691. .P
  692. Secondly, advisory record locking requires a process using locking to
  693. bracket each I/O operation with lock (or test) and unlock operations.
  694. With enforcement-mode file and record locking, a process can lock the
  695. file once and unlock when all I/O operations have been completed.
  696. Enforcement-mode record locking provides a base that can be enhanced;
  697. for example, with sharable locks. That is, the mechanism could be
  698. enhanced to allow a process to lock a file so other processes could
  699. read it, but none of them could write it.
  700. .P
  701. Mandatory locks were omitted for several reasons:
  702. .IP " 1." 4
  703. Mandatory lock setting was done by multiplexing the set-group-ID
  704. bit in most implementations; this was confusing, at best.
  705. .IP " 2." 4
  706. The relationship to file truncation as supported in 4.2 BSD
  707. was not well specified.
  708. .IP " 3." 4
  709. Any publicly readable file could be locked by anyone. Many historical
  710. implementations keep the password database in a publicly readable
  711. file. A malicious user could thus prohibit logins. Another
  712. possibility would be to hold open a long-distance telephone line.
  713. .IP " 4." 4
  714. Some demand-paged historical implementations offer memory mapped files,
  715. and enforcement cannot be done on that type of file.
  716. .P
  717. Since sleeping on a region is interrupted with any signal,
  718. \fIalarm\fR()
  719. may be used to provide a timeout facility in applications requiring
  720. it. This is useful in deadlock detection. Since implementation of
  721. full deadlock detection is not always feasible, the
  722. .BR [EDEADLK]
  723. error was made optional.
  724. .SH "FUTURE DIRECTIONS"
  725. None.
  726. .SH "SEE ALSO"
  727. .IR "\fIalarm\fR\^(\|)",
  728. .IR "\fIclose\fR\^(\|)",
  729. .IR "\fIexec\fR\^",
  730. .IR "\fIkill\fR\^(\|)",
  731. .IR "\fIopen\fR\^(\|)",
  732. .IR "\fIsigaction\fR\^(\|)"
  733. .P
  734. The Base Definitions volume of POSIX.1\(hy2017,
  735. .IR "\fB<fcntl.h>\fP",
  736. .IR "\fB<signal.h>\fP"
  737. .\"
  738. .SH COPYRIGHT
  739. Portions of this text are reprinted and reproduced in electronic form
  740. from IEEE Std 1003.1-2017, Standard for Information Technology
  741. -- Portable Operating System Interface (POSIX), The Open Group Base
  742. Specifications Issue 7, 2018 Edition,
  743. Copyright (C) 2018 by the Institute of
  744. Electrical and Electronics Engineers, Inc and The Open Group.
  745. In the event of any discrepancy between this version and the original IEEE and
  746. The Open Group Standard, the original IEEE and The Open Group Standard
  747. is the referee document. The original Standard can be obtained online at
  748. http://www.opengroup.org/unix/online.html .
  749. .PP
  750. Any typographical or formatting errors that appear
  751. in this page are most likely
  752. to have been introduced during the conversion of the source files to
  753. man page format. To report such errors, see
  754. https://www.kernel.org/doc/man-pages/reporting_bugs.html .