diff options
| author | Alejandro Colomar <alx@kernel.org> | 2025-07-13 23:19:34 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2025-07-20 00:56:30 +0200 |
| commit | 219d7bb11fd41dc349442695f773d82040dc5e6c (patch) | |
| tree | 213dbaf4cbf487766451ba975e52f6bc50549fca | |
| parent | 1717b8889e390e71f5b89e65e3d20438b2927868 (diff) | |
| download | man-pages-219d7bb11fd41dc349442695f773d82040dc5e6c.tar.gz | |
man/man2/fcntl.2, man/man2const/F_NOTIFY.2const: Split F_NOTIFY from fcntl(2)
Signed-off-by: Alejandro Colomar <alx@kernel.org>
| -rw-r--r-- | man/man2/fcntl.2 | 133 | ||||
| -rw-r--r-- | man/man2const/F_NOTIFY.2const | 167 |
2 files changed, 168 insertions, 132 deletions
diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2 index 947db1e0a2..fccfe2c05e 100644 --- a/man/man2/fcntl.2 +++ b/man/man2/fcntl.2 @@ -1044,129 +1044,7 @@ that has been accessed by another process. (This is useful if the caller holds leases against multiple files.) .SS File and directory change notification (dnotify) .TP -.BR F_NOTIFY \~(\f[I]int\f[]) -(Linux 2.4 onward) -Provide notification when the directory referred to by -.I fd -or any of the files that it contains is changed. -The events to be notified are specified in -.IR arg , -which is a bit mask specified by ORing together zero or more of -the following bits: -.P -.RS -.PD 0 -.TP -.B DN_ACCESS -A file was accessed -.RB ( read (2), -.BR pread (2), -.BR readv (2), -and similar) -.TP -.B DN_MODIFY -A file was modified -.RB ( write (2), -.BR pwrite (2), -.BR writev (2), -.BR truncate (2), -.BR ftruncate (2), -and similar). -.TP -.B DN_CREATE -A file was created -.RB ( open (2), -.BR creat (2), -.BR mknod (2), -.BR mkdir (2), -.BR link (2), -.BR symlink (2), -.BR rename (2) -into this directory). -.TP -.B DN_DELETE -A file was unlinked -.RB ( unlink (2), -.BR rename (2) -to another directory, -.BR rmdir (2)). -.TP -.B DN_RENAME -A file was renamed within this directory -.RB ( rename (2)). -.TP -.B DN_ATTRIB -The attributes of a file were changed -.RB ( chown (2), -.BR chmod (2), -.BR utime (2), -.BR utimensat (2), -and similar). -.PD -.RE -.IP -(In order to obtain these definitions, the -.B _GNU_SOURCE -feature test macro must be defined before including -.I any -header files.) -.IP -Directory notifications are normally "one-shot", and the application -must reregister to receive further notifications. -Alternatively, if -.B DN_MULTISHOT -is included in -.IR arg , -then notification will remain in effect until explicitly removed. -.IP -.\" The following does seem a poor API-design choice... -A series of -.B F_NOTIFY -requests is cumulative, with the events in -.I arg -being added to the set already monitored. -To disable notification of all events, make an -.B F_NOTIFY -call specifying -.I arg -as 0. -.IP -Notification occurs via delivery of a signal. -The default signal is -.BR SIGIO , -but this can be changed using the -.B F_SETSIG -operation to -.BR fcntl (). -(Note that -.B SIGIO -is one of the nonqueuing standard signals; -switching to the use of a real-time signal means that -multiple notifications can be queued to the process.) -In the latter case, the signal handler receives a -.I siginfo_t -structure as its second argument (if the handler was -established using -.BR SA_SIGINFO ) -and the -.I si_fd -field of this structure contains the file descriptor which -generated the notification (useful when establishing notification -on multiple directories). -.IP -Especially when using -.BR DN_MULTISHOT , -a real time signal should be used for notification, -so that multiple notifications can be queued. -.IP -.B NOTE: -New applications should use the -.I inotify -interface (available since Linux 2.6.13), -which provides a much superior interface for obtaining notifications of -filesystem events. -See -.BR inotify (7). +.BR F_NOTIFY (2const) .SS Changing the capacity of a pipe .TP .BR F_SETPIPE_SZ (2const) @@ -1287,14 +1165,6 @@ was not specified as zero. .B ENOLCK Too many segment locks open, lock table is full, or a remote locking protocol failed (e.g., locking over NFS). -.TP -.B ENOTDIR -.B F_NOTIFY -was specified in -.IR op , -but -.I fd -does not refer to a directory. .SH VERSIONS POSIX.1-2024 specifies .B FD_CLOFORK @@ -1308,7 +1178,6 @@ POSIX.1-2008. .BR F_SETOWN_EX , .BR F_GETSIG , .BR F_SETSIG , -.BR F_NOTIFY , .BR F_GETLEASE , and .B F_SETLEASE diff --git a/man/man2const/F_NOTIFY.2const b/man/man2const/F_NOTIFY.2const new file mode 100644 index 0000000000..74efcd56b2 --- /dev/null +++ b/man/man2const/F_NOTIFY.2const @@ -0,0 +1,167 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH F_NOTIFY 2const (date) "Linux man-pages (unreleased)" +.SH NAME +F_NOTIFY +\- +file and directory change notification +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include <fcntl.h> +.P +.BI "int fcntl(int " fd ", F_NOTIFY, int " arg ); +.fi +.SH DESCRIPTION +.TP +.BR F_NOTIFY \~(\f[I]int\f[]) +(Linux 2.4 onward) +Provide notification when the directory referred to by +.I fd +or any of the files that it contains is changed. +The events to be notified are specified in +.IR arg , +which is a bit mask specified by ORing together zero or more of +the following bits: +.P +.RS +.PD 0 +.TP +.B DN_ACCESS +A file was accessed +.RB ( read (2), +.BR pread (2), +.BR readv (2), +and similar) +.TP +.B DN_MODIFY +A file was modified +.RB ( write (2), +.BR pwrite (2), +.BR writev (2), +.BR truncate (2), +.BR ftruncate (2), +and similar). +.TP +.B DN_CREATE +A file was created +.RB ( open (2), +.BR creat (2), +.BR mknod (2), +.BR mkdir (2), +.BR link (2), +.BR symlink (2), +.BR rename (2) +into this directory). +.TP +.B DN_DELETE +A file was unlinked +.RB ( unlink (2), +.BR rename (2) +to another directory, +.BR rmdir (2)). +.TP +.B DN_RENAME +A file was renamed within this directory +.RB ( rename (2)). +.TP +.B DN_ATTRIB +The attributes of a file were changed +.RB ( chown (2), +.BR chmod (2), +.BR utime (2), +.BR utimensat (2), +and similar). +.PD +.RE +.IP +(In order to obtain these definitions, the +.B _GNU_SOURCE +feature test macro must be defined before including +.I any +header files.) +.IP +Directory notifications are normally "one-shot", and the application +must reregister to receive further notifications. +Alternatively, if +.B DN_MULTISHOT +is included in +.IR arg , +then notification will remain in effect until explicitly removed. +.IP +.\" The following does seem a poor API-design choice... +A series of +.B F_NOTIFY +requests is cumulative, with the events in +.I arg +being added to the set already monitored. +To disable notification of all events, make an +.B F_NOTIFY +call specifying +.I arg +as 0. +.IP +Notification occurs via delivery of a signal. +The default signal is +.BR SIGIO , +but this can be changed using the +.B F_SETSIG +operation to +.BR fcntl (). +(Note that +.B SIGIO +is one of the nonqueuing standard signals; +switching to the use of a real-time signal means that +multiple notifications can be queued to the process.) +In the latter case, the signal handler receives a +.I siginfo_t +structure as its second argument (if the handler was +established using +.BR SA_SIGINFO ) +and the +.I si_fd +field of this structure contains the file descriptor which +generated the notification (useful when establishing notification +on multiple directories). +.IP +Especially when using +.BR DN_MULTISHOT , +a real time signal should be used for notification, +so that multiple notifications can be queued. +.IP +.B NOTE: +New applications should use the +.I inotify +interface (available since Linux 2.6.13), +which provides a much superior interface for obtaining notifications of +filesystem events. +See +.BR inotify (7). +.SH RETURN VALUE +Zero. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See +.BR fcntl (2). +.TP +.B ENOTDIR +.B F_NOTIFY +was specified in +.IR op , +but +.I fd +does not refer to a directory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux. +.SH SEE ALSO +.BR fcntl (2) |