Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/fcntl.2
Show All 22 Lines | |||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||||||
.\" | .\" | ||||||||
.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 | .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 | ||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||||||
.\" | .\" | ||||||||
.Dd January 6, 2021 | .Dd December 7, 2021 | ||||||||
.Dt FCNTL 2 | .Dt FCNTL 2 | ||||||||
.Os | .Os | ||||||||
.Sh NAME | .Sh NAME | ||||||||
.Nm fcntl | .Nm fcntl | ||||||||
.Nd file control | .Nd file control | ||||||||
.Sh LIBRARY | .Sh LIBRARY | ||||||||
.Lb libc | .Lb libc | ||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||||||
.In fcntl.h | .In fcntl.h | ||||||||
.Ft int | .Ft int | ||||||||
.Fn fcntl "int fd" "int cmd" "..." | .Fn fcntl "int fd" "int cmd" "..." | ||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||||||
The | The | ||||||||
.Fn fcntl | .Fn fcntl | ||||||||
system call provides for control over descriptors. | system call provides for control over descriptors. | ||||||||
The argument | The argument | ||||||||
.Fa fd | .Fa fd | ||||||||
is a descriptor to be operated on by | is a descriptor to be operated on by | ||||||||
.Fa cmd | .Fa cmd | ||||||||
as described below. | as described below. | ||||||||
Depending on the value of | Depending on the value of | ||||||||
.Fa cmd , | .Fa cmd , | ||||||||
.Fn fcntl | .Fn fcntl | ||||||||
can take an additional third argument | can take an additional third argument | ||||||||
.Fa "int arg" . | .Fa "long arg" . | ||||||||
jhb: Maybe just say the type of the 3rd arg depends on the operation (and document the type for each… | |||||||||
kibAuthorUnsubmitted Done Inline ActionsI pushed everything but this change, the review is updated with the man page changes. kib: I pushed everything but this change, the review is updated with the man page changes. | |||||||||
.Bl -tag -width F_DUP2FD_CLOEXEC | .Bl -tag -width F_DUP2FD_CLOEXEC | ||||||||
Done Inline Actionsmaybe "with type dependent on the specific operation" or maybe can take an additional third argument .Fa arg. Unless otherwise noted below for a specific operation, .Fa arg has type .Vt int . emaste: maybe "with type dependent on the specific operation"
or maybe
```
can take an additional… | |||||||||
.It Dv F_DUPFD | .It Dv F_DUPFD | ||||||||
Return a new descriptor as follows: | Return a new descriptor as follows: | ||||||||
.Pp | .Pp | ||||||||
.Bl -bullet -compact -offset 4n | .Bl -bullet -compact -offset 4n | ||||||||
.It | .It | ||||||||
Lowest numbered available descriptor greater than or equal to | Lowest numbered available descriptor greater than or equal to | ||||||||
.Fa arg . | .Fa arg . | ||||||||
.It | .It | ||||||||
▲ Show 20 Lines • Show All 119 Lines • ▼ Show 20 Lines | |||||||||
seals. | seals. | ||||||||
.It Dv F_GET_SEALS | .It Dv F_GET_SEALS | ||||||||
Get seals associated with the file, if the underlying filesystem supports seals. | Get seals associated with the file, if the underlying filesystem supports seals. | ||||||||
.It Dv F_ISUNIONSTACK | .It Dv F_ISUNIONSTACK | ||||||||
Check if the vnode is part of a union stack (either the "union" flag from | Check if the vnode is part of a union stack (either the "union" flag from | ||||||||
.Xr mount 2 | .Xr mount 2 | ||||||||
or unionfs). | or unionfs). | ||||||||
This is a hack not intended to be used outside of libc. | This is a hack not intended to be used outside of libc. | ||||||||
.It Dv F_KINFO | |||||||||
Fills a | |||||||||
Done Inline Actions
markj: | |||||||||
.Vt struct kinfo_file | |||||||||
for the file referenced by the specified file descriptor. | |||||||||
The | |||||||||
.Fa arg | |||||||||
argument should point to the storage for | |||||||||
.Vt struct kinfo_file . | |||||||||
The | |||||||||
.Va kf_structsize | |||||||||
member of the passed structure must be initialized with the sizeof of | |||||||||
.Vt struct kinfo_file , | |||||||||
to allow for the interface versioning and evolution. | |||||||||
.El | .El | ||||||||
.Pp | .Pp | ||||||||
The flags for the | The flags for the | ||||||||
.Dv F_GETFL | .Dv F_GETFL | ||||||||
and | and | ||||||||
.Dv F_SETFL | .Dv F_SETFL | ||||||||
commands are as follows: | commands are as follows: | ||||||||
.Bl -tag -width O_NONBLOCKX | .Bl -tag -width O_NONBLOCKX | ||||||||
▲ Show 20 Lines • Show All 67 Lines • ▼ Show 20 Lines | |||||||||
Seals are on a per-inode basis and require support by the underlying filesystem. | Seals are on a per-inode basis and require support by the underlying filesystem. | ||||||||
If the underlying filesystem does not support seals, | If the underlying filesystem does not support seals, | ||||||||
.Dv F_ADD_SEALS | .Dv F_ADD_SEALS | ||||||||
and | and | ||||||||
.Dv F_GET_SEALS | .Dv F_GET_SEALS | ||||||||
will fail and return | will fail and return | ||||||||
.Dv EINVAL . | .Dv EINVAL . | ||||||||
.Pp | .Pp | ||||||||
Several commands are available for doing advisory file locking; | Several commands are available for doing advisory file locking; | ||||||||
Done Inline ActionsIs "command" or "operation" the better term, in general? I think we should be consistent between this sentence and the added text above/below emaste: Is "command" or "operation" the better term, in general? I think we should be consistent… | |||||||||
they all operate on the following structure: | they all operate on the following structure: | ||||||||
.Bd -literal | .Bd -literal | ||||||||
struct flock { | struct flock { | ||||||||
off_t l_start; /* starting offset */ | off_t l_start; /* starting offset */ | ||||||||
off_t l_len; /* len = 0 means until end of file */ | off_t l_len; /* len = 0 means until end of file */ | ||||||||
pid_t l_pid; /* lock owner */ | pid_t l_pid; /* lock owner */ | ||||||||
short l_type; /* lock type: read/write, etc. */ | short l_type; /* lock type: read/write, etc. */ | ||||||||
short l_whence; /* type of l_start */ | short l_whence; /* type of l_start */ | ||||||||
int l_sysid; /* remote system id or zero for local */ | int l_sysid; /* remote system id or zero for local */ | ||||||||
}; | }; | ||||||||
.Ed | .Ed | ||||||||
The commands available for advisory record locking are as follows: | The commands available for advisory record locking are as follows: | ||||||||
Done Inline ActionsThese commands take a pointer to struct flock as the third argument arg. emaste: These commands take a pointer to struct flock as the third argument arg.
or
These advisory file… | |||||||||
Done Inline ActionsMaybe "operations" here too for consistency? emaste: Maybe "operations" here too for consistency?
But from the context this one is clear so I don't… | |||||||||
.Bl -tag -width F_SETLKWX | .Bl -tag -width F_SETLKWX | ||||||||
.It Dv F_GETLK | .It Dv F_GETLK | ||||||||
Get the first lock that blocks the lock description pointed to by the | Get the first lock that blocks the lock description pointed to by the | ||||||||
third argument, | third argument, | ||||||||
.Fa arg , | .Fa arg , | ||||||||
taken as a pointer to a | taken as a pointer to a | ||||||||
.Fa "struct flock" | .Fa "struct flock" | ||||||||
(see above). | (see above). | ||||||||
▲ Show 20 Lines • Show All 476 Lines • Show Last 20 Lines |
Maybe just say the type of the 3rd arg depends on the operation (and document the type for each operation that takes the third arg) instead of trying to assume it's a single type? In CheriBSD we have a wrapper in libc to deal with this and have fcntl() as a truly var-args function. On existing platforms var-args is close enough to work for passing syscall arguments, but not all ABIs require this. (var-args are passed as a block in a bounded pointer on CHERI platforms and not just a continuation of register arguments).