Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 231 insertions, 0 deletions

diff --git a/man/man2/ioctl.2 b/man/man2/ioctl.2
new file mode 100644
index 0000000..705f5db
--- /dev/null
+++ b/man/man2/ioctl.2
@@ -0,0 +1,231 @@
+.\" Copyright (c) 1980, 1991 Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"     @(#)ioctl.2	6.4 (Berkeley) 3/10/91
+.\"
+.\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
+.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 1999-06-25 by Rachael Munns <vashti@dream.org.uk>
+.\" Modified 2000-09-21 by Andries Brouwer <aeb@cwi.nl>
+.\"
+.TH ioctl 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+ioctl \- control device
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/ioctl.h>
+.P
+.BI "int ioctl(int " fd ", unsigned long " op ", ...);" "\f[R]  /* glibc, BSD */\f[]"
+.BI "int ioctl(int " fd ", int " op ", ...);" "\f[R]            /* musl, other UNIX */\f[]"
+.fi
+.SH DESCRIPTION
+The
+.BR ioctl ()
+system call manipulates the underlying device parameters of special files.
+In particular, many operating characteristics of character special files
+(e.g., terminals) may be controlled with
+.BR ioctl ()
+operations.
+The argument
+.I fd
+must be an open file descriptor.
+.P
+The second argument is a device-dependent operation code.
+The third argument is an untyped pointer to memory.
+It's traditionally
+.BI "char *" argp
+(from the days before
+.B "void *"
+was valid C), and will be so named for this discussion.
+.P
+An
+.BR ioctl ()
+.I op
+has encoded in it whether the argument is an
+.I in
+parameter or
+.I out
+parameter, and the size of the argument
+.I argp
+in bytes.
+Macros and defines used in specifying an
+.BR ioctl ()
+.I op
+are located in the file
+.IR <sys/ioctl.h> .
+See NOTES.
+.SH RETURN VALUE
+Usually, on success zero is returned.
+A few
+.BR ioctl ()
+operations use the return value as an output parameter
+and return a nonnegative value on success.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EBADF
+.I fd
+is not a valid file descriptor.
+.TP
+.B EFAULT
+.I argp
+references an inaccessible memory area.
+.TP
+.B EINVAL
+.I op
+or
+.I argp
+is not valid.
+.TP
+.B ENOTTY
+.I fd
+is not associated with a character special device.
+.TP
+.B ENOTTY
+The specified operation does not apply to the kind of object that the
+file descriptor
+.I fd
+references.
+.SH VERSIONS
+Arguments, returns, and semantics of
+.BR ioctl ()
+vary according to the device driver in question (the call is used as a
+catch-all for operations that don't cleanly fit the UNIX stream I/O
+model).
+.SH STANDARDS
+None.
+.SH HISTORY
+Version\~7 AT&T UNIX has
+.PD 0
+.in +4n
+.nf
+.BI "ioctl(int " fildes ", int " op ", struct sgttyb *" argp );
+.fi
+.in
+.P
+.PD
+(where
+.B struct sgttyb
+has historically been used by
+.BR stty (2)
+and
+.BR gtty (2),
+and is polymorphic by operation type (like a
+.B void *
+would be, if it had been available)).
+.P
+SysIII documents
+.I arg
+without a type at all.
+.P
+4.3BSD has
+.PD 0
+.in +4n
+.nf
+.BI "ioctl(int " d ", unsigned long " op ", char *" argp );
+.fi
+.in
+.P
+.PD
+(with
+.B char *
+similarly in for
+.BR "void *" ).
+.P
+SysVr4 has
+.PD 0
+.in +4n
+.nf
+.BI "int ioctl(int " fildes ", int " op ", ... /* " arg " */);"
+.fi
+.in
+.P
+.PD
+.SH NOTES
+In order to use this call, one needs an open file descriptor.
+Often the
+.BR open (2)
+call has unwanted side effects, that can be avoided under Linux
+by giving it the
+.B O_NONBLOCK
+flag.
+.\"
+.SS ioctl structure
+.\" added two sections - aeb
+Ioctl
+.I op
+values are 32-bit constants.
+In principle these constants are completely arbitrary, but people have
+tried to build some structure into them.
+.P
+The old Linux situation was that of mostly 16-bit constants, where the
+last byte is a serial number, and the preceding byte(s) give a type
+indicating the driver.
+Sometimes the major number was used: 0x03
+for the
+.B HDIO_*
+ioctls, 0x06 for the
+.B LP*
+ioctls.
+And sometimes
+one or more ASCII letters were used.
+For example,
+.B TCGETS
+has value
+0x00005401, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and
+.B CYGETTIMEOUT
+has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
+indicating the cyclades driver.
+.P
+Later (0.98p5) some more information was built into the number.
+One has 2 direction bits
+(00: none, 01: write, 10: read, 11: read/write)
+followed by 14 size bits (giving the size of the argument),
+followed by an 8-bit type (collecting the ioctls in groups
+for a common purpose or a common driver), and an 8-bit
+serial number.
+.P
+The macros describing this structure live in
+.I <asm/ioctl.h>
+and are
+.B _IO(type,nr)
+and
+.BR "{_IOR,_IOW,_IOWR}(type,nr,size)" .
+They use
+.I sizeof(size)
+so that size is a
+misnomer here: this third argument is a data type.
+.P
+Note that the size bits are very unreliable: in lots of cases
+they are wrong, either because of buggy macros using
+.IR sizeof(sizeof(struct)) ,
+or because of legacy values.
+.P
+Thus, it seems that the new structure only gave disadvantages:
+it does not help in checking, but it causes varying values
+for the various architectures.
+.SH SEE ALSO
+.BR execve (2),
+.BR fcntl (2),
+.BR ioctl_console (2),
+.BR ioctl_fat (2),
+.BR ioctl_ficlone (2),
+.BR ioctl_ficlonerange (2),
+.BR ioctl_fideduperange (2),
+.BR ioctl_fslabel (2),
+.BR ioctl_getfsmap (2),
+.BR ioctl_iflags (2),
+.BR ioctl_ns (2),
+.BR ioctl_tty (2),
+.BR ioctl_userfaultfd (2),
+.BR open (2),
+.\" .BR mt (4),
+.BR sd (4),
+.BR tty (4)