From e3f2c8b75008de46cc51802f5915833298216370 Mon Sep 17 00:00:00 2001 Message-Id: From: Josh Triplett Date: Tue, 21 Apr 2020 21:54:25 -0700 Subject: [PATCH] openat2.2, pipe.2, prctl.2: Document O_SPECIFIC_FD and PR_INCREASE_MIN_FD Signed-off-by: Josh Triplett --- man2/openat2.2 | 83 ++++++++++++++++++++++++++++++++++++++++++++++++-- man2/pipe.2 | 42 +++++++++++++++++++++++++ man2/prctl.2 | 12 ++++++++ 3 files changed, 134 insertions(+), 3 deletions(-) diff --git a/man2/openat2.2 b/man2/openat2.2 index fb976f259..994210ad1 100644 --- a/man2/openat2.2 +++ b/man2/openat2.2 @@ -103,9 +103,11 @@ This argument is a pointer to a structure of the following form: .in +4n .EX struct open_how { - u64 flags; /* O_* flags */ - u64 mode; /* Mode for O_{CREAT,TMPFILE} */ - u64 resolve; /* RESOLVE_* flags */ + u64 flags; /* O_* flags */ + u64 mode; /* Mode for O_{CREAT,TMPFILE} */ + u64 resolve; /* RESOLVE_* flags */ + u32 fd; /* File descriptor for O_SPECIFIC_FD */ + u32 __padding; /* Must be zeroed */ /* ... */ }; .EE @@ -147,6 +149,12 @@ argument, .BR openat2 () returns an error if unknown or conflicting flags are specified in .IR how.flags . +.IP +The flag +.B O_SPECIFIC_FD +is only valid for openat2, as it requires the +.I fd +field. .TP .I mode This field specifies the @@ -390,6 +398,48 @@ so that a pathname component (now) contains a bind mount. If any bits other than those listed above are set in .IR how.resolve , an error is returned. +.TP +.I fd +If +.I flags +contains +.BR O_SPECIFIC_FD , +.BR openat2 () +will allocate and return that specific file descriptor, rather than using the +lowest available file descriptor. +If +.I fd +contains \-1, +.BR openat2 () +will return the lowest available file descriptor just as if +.B O_SPECIFIC_FD +had not been specified. +.IP +The caller may wish to use the +.BR prctl (2) +option +.B PR_INCREASE_MIN_FD +to reserve a range of file descriptors for such usage. +.IP +If the specified file descriptor is already in use, +.BR openat2 () +will return \-1 and set +.I errno +to +.BR EBUSY . +.IP +If +.I flags +does not contain +.BR O_SPECIFIC_FD , +.I fd +must be zero. +.TP +.I __padding +This value must be zero, and must not be referenced by name. +Future versions of the +.I open_how +structure may give a new name and semantic to this field. .SH RETURN VALUE On success, a new file descriptor is returned. On error, \-1 is returned, and @@ -421,6 +471,26 @@ The caller may choose to retry the .BR openat2 () call. .TP +.B EBUSY +.I how.flags +contains +.B O_SPECIFIC_FD +and the file descriptor specified in +.I fd +was in use. +.TP +.B EMFILE +.I how.flags +contains +.B O_SPECIFIC_FD +and +.I how.fd +exceeds the maximum file descriptor allowed for the process +(see the description of +.BR RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP .B EINVAL An unknown flag or invalid value was specified in .IR how . @@ -435,6 +505,13 @@ or .BR O_TMPFILE . .TP .B EINVAL +.I how.fd +is non-zero, but +.I how.flags +does not contain +.BR O_SPECIFIC_FD . +.TP +.B EINVAL .I size was smaller than any known version of .IR "struct open_how" . diff --git a/man2/pipe.2 b/man2/pipe.2 index 4a5a10567..af07b9c59 100644 --- a/man2/pipe.2 +++ b/man2/pipe.2 @@ -146,6 +146,31 @@ referred to by the new file descriptors. Using this flag saves extra calls to .BR fcntl (2) to achieve the same result. +.TP +.B O_SPECIFIC_FD +Rather than allocating the next available file descriptors, read the file +descriptor values specified in +.I pipefd +and allocate those specific file descriptors. +If one or both of the entries in +.I pipefd +contains \-1, +.BR pipe2 () +will allocate the lowest available file descriptor for that end of the pipe as +usual. +.IP +The caller may wish to use the +.BR prctl (2) +option +.B PR_INCREASE_MIN_FD +to reserve a range of file descriptors for such usage. +.IP +If the specified file descriptor is already in use, +.BR pipe2 () +will return \-1 and set +.I errno +to +.BR EBUSY . .SH RETURN VALUE On success, zero is returned. On error, \-1 is returned, @@ -169,6 +194,12 @@ likewise does not modify on failure. .SH ERRORS .TP +.B EBUSY +.I flags +contains +.B O_SPECIFIC_FD +and one of the specified file descriptors was in use. +.TP .B EFAULT .I pipefd is not valid. @@ -181,6 +212,17 @@ Invalid value in .B EMFILE The per-process limit on the number of open file descriptors has been reached. .TP +.B EMFILE +.I flags +contains +.B O_SPECIFIC_FD +and one of the specified file descriptors exceeds the maximum file descriptor +allowed for the process +(see the description of +.BR RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP .B ENFILE The system-wide limit on the total number of open files has been reached. .TP diff --git a/man2/prctl.2 b/man2/prctl.2 index 7a5af76f4..d54d9cb67 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -531,6 +531,18 @@ All unused .BR prctl () arguments must be zero. .TP +.BR PR_INCREASE_MIN_FD " (since Linux 5.8)" +Increase the minimum file descriptor that the kernel will automatically +allocate when the process opens a new file descriptor, by +.IR arg2 . +Return (as the function result) the current minimum. +A process may pass 0 as +.I arg2 +to return the current minimum without changing it. +The remaining unused +.BR prctl () +arguments must be zero for future compatibility. +.TP .BR PR_SET_MM " (since Linux 3.3)" .\" commit 028ee4be34a09a6d48bdf30ab991ae933a7bc036 Modify certain kernel memory map descriptor fields -- 2.26.2