diff options
Diffstat (limited to 'man2/open.2')
| -rw-r--r-- | man2/open.2 | 295 |
1 files changed, 145 insertions, 150 deletions
diff --git a/man2/open.2 b/man2/open.2 index 19115a372..52286f634 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -28,7 +28,7 @@ .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and .\" O_TTYINIT. Eventually these may need to be documented. --mtk .\" -.TH open 2 2023-02-05 "Linux man-pages 6.03" +.TH open 2 2023-05-20 "Linux man-pages 6.05.01" .SH NAME open, openat, creat \- open and possibly create a file .SH LIBRARY @@ -38,18 +38,17 @@ Standard C library .nf .B #include <fcntl.h> .PP -.BI "int open(const char *" pathname ", int " flags ); -.BI "int open(const char *" pathname ", int " flags ", mode_t " mode ); +.BI "int open(const char *" pathname ", int " flags ", ..." +.BI " \fR/*\fP mode_t " mode " \fR*/\fP );" .PP .BI "int creat(const char *" pathname ", mode_t " mode ); .PP -.BI "int openat(int " dirfd ", const char *" pathname ", int " flags ); -.BI "int openat(int " dirfd ", const char *" pathname ", int " flags \ -", mode_t " mode ); +.BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..." +.BI " \fR/*\fP mode_t " mode " \fR*/\fP );" .PP /* Documented separately, in \fBopenat2\fP(2): */ .BI "int openat2(int " dirfd ", const char *" pathname , -.BI " const struct open_how *" how ", size_t " size ");" +.BI " const struct open_how *" how ", size_t " size ); .fi .PP .RS -4 @@ -123,7 +122,7 @@ respectively. .PP In addition, zero or more file creation flags and file status flags can be -.RI bitwise- or 'd +bitwise ORed in .IR flags . The @@ -803,16 +802,16 @@ permanent, using code like the following: char path[PATH_MAX]; fd = open("/path/to/dir", O_TMPFILE | O_RDWR, S_IRUSR | S_IWUSR); - +\& /* File I/O on \[aq]fd\[aq]... */ - +\& linkat(fd, "", AT_FDCWD, "/path/for/file", AT_EMPTY_PATH); - +\& /* If the caller doesn\[aq]t have the CAP_DAC_READ_SEARCH capability (needed to use AT_EMPTY_PATH with linkat(2)), and there is a proc(5) filesystem mounted, then the linkat(2) call above can be replaced with: - +\& snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd); linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file", AT_SYMLINK_FOLLOW); @@ -1285,19 +1284,133 @@ flag was specified, and an incompatible lease was held on the file (see .BR fcntl (2)). .SH VERSIONS +The (undefined) effect of +.B O_RDONLY | O_TRUNC +varies among implementations. +On many systems the file is actually truncated. +.\" Linux 2.0, 2.5: truncate +.\" Solaris 5.7, 5.8: truncate +.\" Irix 6.5: truncate +.\" Tru64 5.1B: truncate +.\" HP-UX 11.22: truncate +.\" FreeBSD 4.7: truncate +.SS Synchronized I/O +The POSIX.1-2008 "synchronized I/O" option +specifies different variants of synchronized I/O, +and specifies the +.BR open () +flags +.BR O_SYNC , +.BR O_DSYNC , +and +.B O_RSYNC +for controlling the behavior. +Regardless of whether an implementation supports this option, +it must at least support the use of +.B O_SYNC +for regular files. +.PP +Linux implements +.B O_SYNC +and +.BR O_DSYNC , +but not +.BR O_RSYNC . +Somewhat incorrectly, glibc defines +.B O_RSYNC +to have the same value as +.BR O_SYNC . +.RB ( O_RSYNC +is defined in the Linux header file +.I <asm/fcntl.h> +on HP PA-RISC, but it is not used.) +.PP +.B O_SYNC +provides synchronized I/O +.I file +integrity completion, +meaning write operations will flush data and all associated metadata +to the underlying hardware. +.B O_DSYNC +provides synchronized I/O +.I data +integrity completion, +meaning write operations will flush data +to the underlying hardware, +but will only flush metadata updates that are required +to allow a subsequent read operation to complete successfully. +Data integrity completion can reduce the number of disk operations +that are required for applications that don't need the guarantees +of file integrity completion. +.PP +To understand the difference between the two types of completion, +consider two pieces of file metadata: +the file last modification timestamp +.RI ( st_mtime ) +and the file length. +All write operations will update the last file modification timestamp, +but only writes that add data to the end of the +file will change the file length. +The last modification timestamp is not needed to ensure that +a read completes successfully, but the file length is. +Thus, +.B O_DSYNC +would only guarantee to flush updates to the file length metadata +(whereas +.B O_SYNC +would also always flush the last modification timestamp metadata). +.PP +Before Linux 2.6.33, Linux implemented only the +.B O_SYNC +flag for +.BR open (). +However, when that flag was specified, +most filesystems actually provided the equivalent of synchronized I/O +.I data +integrity completion (i.e., +.B O_SYNC +was actually implemented as the equivalent of +.BR O_DSYNC ). +.PP +Since Linux 2.6.33, proper +.B O_SYNC +support is provided. +However, to ensure backward binary compatibility, +.B O_DSYNC +was defined with the same value as the historical +.BR O_SYNC , +and +.B O_SYNC +was defined as a new (two-bit) flag value that includes the +.B O_DSYNC +flag value. +This ensures that applications compiled against +new headers get at least +.B O_DSYNC +semantics before Linux 2.6.33. +.\" +.SS C library/kernel differences +Since glibc 2.26, +the glibc wrapper function for +.BR open () +employs the .BR openat () -was added in Linux 2.6.16; -library support was added in glibc 2.4. +system call, rather than the kernel's +.BR open () +system call. +For certain architectures, this is also true before glibc 2.26. +.\" .SH STANDARDS -.BR open (), +.TP +.BR open () +.TQ .BR creat () -SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. -.PP -.BR openat (): +.TQ +.BR openat () POSIX.1-2008. .PP .BR openat2 (2) -is Linux-specific. +Linux. .PP The .BR O_DIRECT , @@ -1324,17 +1437,17 @@ with a value greater than or equal to 200809L or with a value greater than or equal to 700. In glibc 2.11 and earlier, one obtains the definitions by defining .BR _GNU_SOURCE . -.PP -As noted in -.BR feature_test_macros (7), -feature test macros such as -.BR _POSIX_C_SOURCE , -.BR _XOPEN_SOURCE , -and -.B _GNU_SOURCE -must be defined before including -.I any -header files. +.SH HISTORY +.TP +.BR open () +.TQ +.BR creat () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR openat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. .SH NOTES Under Linux, the .B O_NONBLOCK @@ -1345,17 +1458,6 @@ this may be used to open a device in order to get a file descriptor for use with .BR ioctl (2). .PP -The (undefined) effect of -.B O_RDONLY | O_TRUNC -varies among implementations. -On many systems the file is actually truncated. -.\" Linux 2.0, 2.5: truncate -.\" Solaris 5.7, 5.8: truncate -.\" Irix 6.5: truncate -.\" Tru64 5.1B: truncate -.\" HP-UX 11.22: truncate -.\" FreeBSD 4.7: truncate -.PP Note that .BR open () can open device special files, but @@ -1388,11 +1490,11 @@ and fields are set to the current time. .PP The files in the -.I /proc/[pid]/fd +.IR /proc/ pid /fd directory show the open file descriptors of the process with the PID .IR pid . The files in the -.I /proc/[pid]/fdinfo +.IR /proc/ pid /fdinfo directory show even more information about these file descriptors. See .BR proc (5) @@ -1442,113 +1544,6 @@ operation to test whether two file descriptors (in the same process or in two different processes) refer to the same open file description. .\" -.\" -.SS Synchronized I/O -The POSIX.1-2008 "synchronized I/O" option -specifies different variants of synchronized I/O, -and specifies the -.BR open () -flags -.BR O_SYNC , -.BR O_DSYNC , -and -.B O_RSYNC -for controlling the behavior. -Regardless of whether an implementation supports this option, -it must at least support the use of -.B O_SYNC -for regular files. -.PP -Linux implements -.B O_SYNC -and -.BR O_DSYNC , -but not -.BR O_RSYNC . -Somewhat incorrectly, glibc defines -.B O_RSYNC -to have the same value as -.BR O_SYNC . -.RB ( O_RSYNC -is defined in the Linux header file -.I <asm/fcntl.h> -on HP PA-RISC, but it is not used.) -.PP -.B O_SYNC -provides synchronized I/O -.I file -integrity completion, -meaning write operations will flush data and all associated metadata -to the underlying hardware. -.B O_DSYNC -provides synchronized I/O -.I data -integrity completion, -meaning write operations will flush data -to the underlying hardware, -but will only flush metadata updates that are required -to allow a subsequent read operation to complete successfully. -Data integrity completion can reduce the number of disk operations -that are required for applications that don't need the guarantees -of file integrity completion. -.PP -To understand the difference between the two types of completion, -consider two pieces of file metadata: -the file last modification timestamp -.RI ( st_mtime ) -and the file length. -All write operations will update the last file modification timestamp, -but only writes that add data to the end of the -file will change the file length. -The last modification timestamp is not needed to ensure that -a read completes successfully, but the file length is. -Thus, -.B O_DSYNC -would only guarantee to flush updates to the file length metadata -(whereas -.B O_SYNC -would also always flush the last modification timestamp metadata). -.PP -Before Linux 2.6.33, Linux implemented only the -.B O_SYNC -flag for -.BR open (). -However, when that flag was specified, -most filesystems actually provided the equivalent of synchronized I/O -.I data -integrity completion (i.e., -.B O_SYNC -was actually implemented as the equivalent of -.BR O_DSYNC ). -.PP -Since Linux 2.6.33, proper -.B O_SYNC -support is provided. -However, to ensure backward binary compatibility, -.B O_DSYNC -was defined with the same value as the historical -.BR O_SYNC , -and -.B O_SYNC -was defined as a new (two-bit) flag value that includes the -.B O_DSYNC -flag value. -This ensures that applications compiled against -new headers get at least -.B O_DSYNC -semantics before Linux 2.6.33. -.\" -.SS C library/kernel differences -Since glibc 2.26, -the glibc wrapper function for -.BR open () -employs the -.BR openat () -system call, rather than the kernel's -.BR open () -system call. -For certain architectures, this is also true before glibc 2.26. -.\" .SS NFS There are many infelicities in the protocol underlying NFS, affecting amongst others |