464 lines
15 KiB
HTML
464 lines
15 KiB
HTML
<html><!-- This HTML file has been created by texi2html 1.29
|
|
from syscalls.texi on 4 June 1994 -->
|
|
|
|
<TITLE>Syscall specifications of Linux - ioctl</TITLE>
|
|
<P>Go to the <A HREF="syscalls_16.html" tppabs="http://www.infran.ru/TechInfo/syscalls/syscalls_16.html">previous</A>, <A HREF="syscalls_18.html" tppabs="http://www.infran.ru/TechInfo/syscalls/syscalls_18.html">next</A> section.<P>
|
|
<H2><A NAME="SEC17" HREF="syscalls_toc.html#SEC17" tppabs="http://www.infran.ru/TechInfo/syscalls/syscalls_toc.html#SEC17">ioctl</A></H2>
|
|
<P>
|
|
<H3>SYNOPSIS</H3>
|
|
<P>
|
|
<CODE>int ioctl(int <VAR>d</VAR>, int <VAR>cmd</VAR>, ...);</CODE>
|
|
<P>
|
|
The third argument is called <CODE>char *<VAR>argp</VAR></CODE>.
|
|
<P>
|
|
<H3>PARAMETERS</H3>
|
|
<P>
|
|
<VAR>d</VAR>: [in] the file descriptor of the file to manipulate.
|
|
<P>
|
|
<VAR>cmd</VAR>: [in] the type of request.
|
|
<P>
|
|
<VAR>argp</VAR>: depends on the request.
|
|
<P>
|
|
<H3>DESCRIPTION</H3>
|
|
<P>
|
|
Controls the io parameters of character special devices (tty, mt, etc.).
|
|
The values that <VAR>cmd</VAR> may take for file operations are:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT><CODE>FIOCLEX</CODE>
|
|
<DD>Sets the close-on-exec flag of the file.
|
|
<P>
|
|
<DT><CODE>FIONCLEX</CODE>
|
|
<DD>Clears the close-on-exec flag of the file.
|
|
<P>
|
|
<DT><CODE>FIONBIO</CODE>
|
|
<DD>If <VAR>argp</VAR> is true, sets the file <CODE>O_NONBLOCK</CODE> flag, otherwise it
|
|
clears the flag.
|
|
<P>
|
|
<DT><CODE>FIOASYNC</CODE>
|
|
<DD>If <VAR>argp</VAR> is true, sets the file <CODE>O_SYNC</CODE> flag, otherwise it
|
|
clears the flag. (This flag is not used as of Linux 1.0.)
|
|
<P>
|
|
<DT><CODE>FIONREAD</CODE>
|
|
<DD>Returns to a buffer pointed to by <VAR>argp</VAR>, the number of bytes
|
|
immediately readable from the file.
|
|
<P>
|
|
<DT><CODE>FIOSETOWN</CODE>
|
|
<DD>Sets the owner of the file to <VAR>argp</VAR> (a pid). The owner is the one
|
|
that receives the <CODE>SIGURG</CODE> and <CODE>SIGIO</CODE> signals. (Only for
|
|
sockets.)
|
|
<P>
|
|
<DT><CODE>FIOGETOWN</CODE>
|
|
<DD>Returns the owner of the file to a buffer pointed to by <VAR>argp</VAR>.
|
|
(Only for sockets.)
|
|
<P>
|
|
<DT><CODE>FIGETBSZ</CODE>
|
|
<DD>Returns the block size of the file to a buffer pointed to by <VAR>argp</VAR>.
|
|
(Seems non-standard.)
|
|
<P>
|
|
<DT><CODE>FIBMAP</CODE>
|
|
<DD>Returns the block number in the fs corresponding to the <VAR>argp</VAR>'th
|
|
block in the file. (I have guessed right? Anyway, this is non-standard.)
|
|
</DL>
|
|
|
|
The values for magnetic tape operations are:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT><CODE>MTIOCTOP</CODE>
|
|
<DD>Perform an operation on a magnetic tape. <VAR>argp</VAR> is a pointer to a
|
|
<CODE>mtop</CODE> structure.
|
|
<P>
|
|
<DT><CODE>MTIOCGET</CODE>
|
|
<DD>Get magnetic tape status. <VAR>argp</VAR> is a pointer to a <CODE>mtget</CODE>
|
|
structure.
|
|
<P>
|
|
<DT><CODE>MTIOCPOS</CODE>
|
|
<DD>Set magnetic tape position. <VAR>argp</VAR> points to a long integer
|
|
specifying the block number to go to.
|
|
</DL>
|
|
<P>
|
|
The section on magnetic tapes will remain incomplete for a while... I
|
|
don't have a clue how it is supposed to work.
|
|
<P>
|
|
The values for sockets operations are:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT><CODE>SIOCSPGRP</CODE>
|
|
<DD>Same as <CODE>FIOSETOWN</CODE>.
|
|
<P>
|
|
<DT><CODE>SIOCGPGRP</CODE>
|
|
<DD>Same as <CODE>FIOGETOWN</CODE>.
|
|
<P>
|
|
<DT><CODE>SIOCATMARK</CODE>
|
|
<DD>Not supported.
|
|
<P>
|
|
<DT><CODE>SIOCADDRT</CODE>
|
|
<DD>Adds a routing entry in the routing table of the system. The task must
|
|
have superuser privileges to perform that operation. <VAR>argp</VAR> points
|
|
to a <CODE>rtentry</CODE> structure.
|
|
<P>
|
|
<DT><CODE>SIOCDELRT</CODE>
|
|
<DD>Removes a routing entry from the routing table of the system. The task
|
|
must have superuser privileges to perform that operation. <VAR>argp</VAR>
|
|
points to a <CODE>rtentry</CODE> structure.
|
|
<P>
|
|
<DT><CODE>SIOCADDRTOLD</CODE>
|
|
<DD>Same as <CODE>SIOCADDRT</CODE> but uses an <CODE>old_rtentry</CODE> structure.
|
|
Obsolete. Do not use.
|
|
<P>
|
|
<DT><CODE>SIOCDELRTOLD</CODE>
|
|
<DD>Same as <CODE>SIOCDELRT</CODE> but uses an <CODE>old_rtentry</CODE> structure.
|
|
Obsolete. Do not use.
|
|
<P>
|
|
<DT><CODE>SIOCDARP</CODE>
|
|
<DD>Deletes an ARP entry. The calling task must have superuser privileges.
|
|
<VAR>argp</VAR> points to an <CODE>arpreq</CODE> structure.
|
|
<P>
|
|
<DT><CODE>SIOCGARP</CODE>
|
|
<DD>Retreive an ARP entry. The calling task must have superuser privileges.
|
|
<VAR>argp</VAR> points to an <CODE>arpreq</CODE> structure.
|
|
<P>
|
|
<DT><CODE>SIOCSARP</CODE>
|
|
<DD>Sets an ARP entry. The calling task must have superuser privileges.
|
|
<VAR>argp</VAR> points to an <CODE>arpreq</CODE> structure.
|
|
<P>
|
|
<DT><CODE>IP_SET_DEV</CODE>
|
|
<DD>Not supported.
|
|
<P>
|
|
<DT><CODE>SIOCGIFCONF</CODE>
|
|
<DD>Reteives the network interface configuration list in a <CODE>ifconf</CODE>
|
|
structure.
|
|
<P>
|
|
<DT><CODE>SIOCGIFFLAGS</CODE>
|
|
<DD>Gets the interface flags. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFFLAGS</CODE>
|
|
<DD>Sets the interface flags. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>SIOCGIFADDR</CODE>
|
|
<DD>Gets the interface address. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFADDR</CODE>
|
|
<DD>Sets the interface address. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>SIOCGIFDSTADDR</CODE>
|
|
<DD>Gets the interface remote address. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFDSTADDR</CODE>
|
|
<DD>Sets the interface remote address. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>SIOCGIFBRDADDR</CODE>
|
|
<DD>Gets the interface broadcast address. <VAR>argp</VAR> points to an
|
|
<CODE>ifreq</CODE> structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFBRDADDR</CODE>
|
|
<DD>Sets the interface broadcast address. <VAR>argp</VAR> points to an
|
|
<CODE>ifreq</CODE> structure. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>SIOCGIFNETMASK</CODE>
|
|
<DD>Gets the interface network mask. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFNETMASK</CODE>
|
|
<DD>Sets the interface network mask. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>SIOCGIFMETRIC</CODE>
|
|
<DD>Gets the interface routing metric. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFMETRIC</CODE>
|
|
<DD>Sets the interface routing metric. <VAR>argp</VAR> points to an <CODE>ifreq</CODE>
|
|
structure. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>SIOCGIFMEM or SIOCSIFMEM</CODE>
|
|
<DD>Not supported.
|
|
<P>
|
|
<DT><CODE>SIOCGIFMTU</CODE>
|
|
<DD>Gets the interface maximum transmission unit. <VAR>argp</VAR> points to an
|
|
<CODE>ifreq</CODE> structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFMTU</CODE>
|
|
<DD>Sets the interface maximum transmission unit. <VAR>argp</VAR> points to an
|
|
<CODE>ifreq</CODE> structure. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>SIOCSIFLINK</CODE>
|
|
<DD>Links in an I/O driver into the operating system kernel.
|
|
<P>
|
|
<DT><CODE>SIOCGIFHWADDR</CODE>
|
|
<DD>Gets the interface hardware address. <VAR>argp</VAR> points to an
|
|
<CODE>ifreq</CODE> structure.
|
|
<P>
|
|
<DT><CODE>SIOCSIFHWADDR</CODE>
|
|
<DD>Not supported.
|
|
<P>
|
|
<DT><CODE>SIOCGIFNAME</CODE>
|
|
<DD>Not supported.
|
|
<P>
|
|
<DT><CODE>DDIOCSDBG:</CODE>
|
|
<DD>Set the DDI debug level.
|
|
</DL>
|
|
<P>
|
|
<PRE>
|
|
struct rtentry {
|
|
unsigned long rt_hash; /* hash key for lookups */
|
|
struct sockaddr rt_dst; /* target address */
|
|
struct sockaddr rt_gateway; /* gateway addr (RTF_GATEWAY) */
|
|
struct sockaddr rt_genmask; /* target network mask (IP) */
|
|
short rt_flags;
|
|
short rt_refcnt;
|
|
unsigned long rt_use;
|
|
struct ifnet *rt_ifp;
|
|
short rt_metric; /* +1 for binary compatibility! */
|
|
char *rt_dev; /* forcing the device at add */
|
|
};
|
|
</PRE>
|
|
<P>
|
|
<PRE>
|
|
struct old_rtentry {
|
|
unsigned long rt_genmask;
|
|
struct sockaddr rt_dst;
|
|
struct sockaddr rt_gateway;
|
|
short rt_flags;
|
|
short rt_refcnt;
|
|
unsigned long rt_use;
|
|
char *rt_dev;
|
|
};
|
|
</PRE>
|
|
<P>
|
|
<VAR>rt_flags</VAR> is a or'ed combinaison of one or more of the following:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT><CODE>RTF_UP</CODE>
|
|
<DD>the route is usable.
|
|
<P>
|
|
<DT><CODE>RTF_GATEWAY</CODE>
|
|
<DD>the destination is a gateway.
|
|
<P>
|
|
<DT><CODE>RTF_HOST</CODE>
|
|
<DD>the entry is a host. (If this flag is not set, the entry is a net.)
|
|
</DL>
|
|
<P>
|
|
<PRE>
|
|
struct arpreq {
|
|
struct sockaddr arp_pa; /* protocol address */
|
|
struct sockaddr arp_ha; /* hardware address */
|
|
int arp_flags; /* flags */
|
|
};
|
|
</PRE>
|
|
<P>
|
|
The <CODE>arp_flags</CODE> member may be one or more or'ed values of the
|
|
following:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT><CODE>ATF_INUSE</CODE>
|
|
<DD>the entry is in use.
|
|
<P>
|
|
<DT><CODE>ATF_COM</CODE>
|
|
<DD>the entry is complete (ha is valid).
|
|
<P>
|
|
<DT><CODE>ATF_PERM</CODE>
|
|
<DD>the entry is permanent.
|
|
<P>
|
|
<DT><CODE>ATF_PUBL</CODE>
|
|
<DD>publish entry.
|
|
<P>
|
|
<DT><CODE>ATF_USETRAILERS</CODE>
|
|
<DD>has requested trailers.
|
|
</DL>
|
|
<P>
|
|
Here is the layout of the <CODE>ifconf</CODE> structure used to get the
|
|
configuration list:
|
|
<P>
|
|
<PRE>
|
|
struct ifconf {
|
|
int ifc_len; /* size of buffer */
|
|
union {
|
|
caddr_t ifcu_buf;
|
|
struct ifreq *ifcu_req;
|
|
} ifc_ifcu;
|
|
};
|
|
</PRE>
|
|
<P>
|
|
Here is the layout of the <CODE>ifreq</CODE> structure used to send/receive
|
|
interface data:
|
|
<P>
|
|
<PRE>
|
|
struct ifreq {
|
|
#define IFHWADDRLEN 6
|
|
#define IFNAMSIZ 16
|
|
union {
|
|
char ifrn_name[IFNAMSIZ]; /* if name, e.g. "en0" */
|
|
char ifrn_hwaddr[IFHWADDRLEN];
|
|
} ifr_ifrn;
|
|
union {
|
|
struct sockaddr ifru_addr;
|
|
struct sockaddr ifru_dstaddr;
|
|
struct sockaddr ifru_broadaddr;
|
|
struct sockaddr ifru_netmask;
|
|
short ifru_flags;
|
|
int ifru_metric;
|
|
int ifru_mtu;
|
|
caddr_t ifru_data;
|
|
} ifr_ifru;
|
|
};
|
|
</PRE>
|
|
<P>
|
|
For terminal I/O, the following commands may be used:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT><CODE>TCGETS</CODE>
|
|
<DD>Gets the <CODE>termios</CODE> structure associated with the terminal.
|
|
<VAR>argp</VAR> points to a <CODE>termios</CODE> structure.
|
|
<P>
|
|
<DT><CODE>TCSETS</CODE>
|
|
<DD>Sets the <CODE>termios</CODE> structure associated with the terminal. The
|
|
change is immediate. <VAR>argp</VAR> points to a <CODE>termios</CODE> structure.
|
|
<P>
|
|
<DT><CODE>TCSETSW</CODE>
|
|
<DD>Same as <CODE>TCSETS</CODE> but wait until the output buffer is empty before
|
|
performing the change.
|
|
<P>
|
|
<DT><CODE>TCSETSF</CODE>
|
|
<DD>Same as <CODE>TCSETS</CODE> but wait until the output buffer is empty and
|
|
flushes the input buffer before performing the change.
|
|
<P>
|
|
<DT><CODE>TCGETA</CODE>
|
|
<DD>Gets the <CODE>termio</CODE> structure associated with the terminal.
|
|
<VAR>argp</VAR> points to a <CODE>termio</CODE> structure.
|
|
<P>
|
|
<DT><CODE>TCSETS</CODE>
|
|
<DD>Sets the <CODE>termio</CODE> structure associated with the terminal. The
|
|
change is immediate. <VAR>argp</VAR> points to a <CODE>termio</CODE> structure.
|
|
<P>
|
|
<DT><CODE>TCSETAW</CODE>
|
|
<DD>Same as <CODE>TCSETA</CODE> but wait until the output buffer is empty before
|
|
performing the change.
|
|
<P>
|
|
<DT><CODE>TCSETAF</CODE>
|
|
<DD>Same as <CODE>TCSETA</CODE> but wait until the output buffer is empty and
|
|
flushes the input buffer before performing the change.
|
|
<P>
|
|
<DT><CODE>TCXONC</CODE>
|
|
<DD>Starts or stops the tty flow. <VAR>argp</VAR> may be one of the following:
|
|
<P>
|
|
<DT><CODE>TCOOFF</CODE>
|
|
<DD>Stops output.
|
|
<P>
|
|
<DT><CODE>TCOON</CODE>
|
|
<DD>Restart output.
|
|
<P>
|
|
<DT><CODE>TCIOFF</CODE>
|
|
<DD>Stops input.
|
|
<P>
|
|
<DT><CODE>TCION</CODE>
|
|
<DD>Restart input.
|
|
<P>
|
|
<DT><CODE>TCFLSH</CODE>
|
|
<DD>Flushes the tty. <VAR>argp</VAR> may be <CODE>TCIFLUSH</CODE> to flush the input,
|
|
<CODE>TCOFLUSH</CODE> to flush the output or <CODE>TCIOFLUSH</CODE> to flush both.
|
|
<P>
|
|
<DT><CODE>TIOCEXCL</CODE>
|
|
<DD>Sets the tty in exclusive mode. No further <CODE>open</CODE> operations on the
|
|
terminal are permited.
|
|
<P>
|
|
<DT><CODE>TIOCNXCL</CODE>
|
|
<DD>Disable exclusive mode. <CODE>open</CODE> operations are now permitted.
|
|
<P>
|
|
<DT><CODE>TIOCSCTTY</CODE>
|
|
<DD>Sets that termial as the controlling terminal of the current task. The
|
|
calling task must be a session leader and not have a controlling tty
|
|
already. If the task does not have superuser privileges, normal
|
|
authorisations checks are performed. If the task has superuser
|
|
privileges and <VAR>argp</VAR> is set to 1, the terminal will be set as the
|
|
controling terminal even if it was already the controling terminal of
|
|
another task.
|
|
<P>
|
|
<DT><CODE>TIOCGPGRP</CODE>
|
|
<DD>Gets the process group id associated with this terminal. <VAR>argp</VAR>
|
|
points to an integer that is set to that id.
|
|
<P>
|
|
<DT><CODE>TIOCSPGRP</CODE>
|
|
<DD>Associate the terminal to the process group which has an id equals to
|
|
<VAR>argp</VAR>. The processes of the process group must have the same real
|
|
or saved uid of as the effective or save uid of the calling task, or be
|
|
descendants of the calling process or the calling process must have
|
|
superuser privileges.
|
|
<P>
|
|
<DT><CODE>TIOCOUTQ</CODE>
|
|
<DD>Sets an integer pointed to by <VAR>argp</VAR> to the number of bytes in the
|
|
output queue that are not sent.
|
|
<P>
|
|
<DT><CODE>TIOCSTI</CODE>
|
|
<DD>Insert the value of <VAR>argp</VAR> into the input queue of the terminal.
|
|
<P>
|
|
<DT><CODE>TIOCGWINSZ</CODE>
|
|
<DD>Returns the window size into a <CODE>winsize</CODE> structure pointed to by
|
|
<VAR>argp</VAR>.
|
|
<P>
|
|
<DT><CODE>TIOCSWINSZ</CODE>
|
|
<DD>Sets the window size to the <CODE>winsize</CODE> structure pointed to by
|
|
<VAR>argp</VAR>.
|
|
<P>
|
|
<DT><CODE>TIOCCONS</CODE>
|
|
<DD>Controls the redirection of the console. If <VAR>fd</VAR> is a console, the
|
|
redirection is cancelled. If <VAR>fd</VAR> is a pseudo console slave, the
|
|
console is redirected to that slave. If <VAR>fd</VAR> is a pseudo console
|
|
master, the console is redirected to its slave. The calling taks must be
|
|
have superuser privileges.
|
|
<P>
|
|
<DT><CODE>TIOCNOTTY</CODE>
|
|
<DD>Dissociate the controling terminal from the current task. The calling
|
|
task must be process leader.
|
|
<P>
|
|
<DT><CODE>TIOCGETD</CODE>
|
|
<DD>Retreives the terminal current line discipline mode. The value is store
|
|
to the area pointed to by <VAR>argp</VAR>.
|
|
<P>
|
|
<DT><CODE>TIOCSETD</CODE>
|
|
<DD>Sets the terminal line discipline mode to the value of <VAR>argp</VAR>.
|
|
<P>
|
|
<DT><CODE>TIOCGLCKTRMIOS</CODE>
|
|
<DD>Gets the locking status of the <CODE>termios</CODE> structure of the terminal.
|
|
<VAR>argp</VAR> points to a <VAR>termios</VAR> structure.
|
|
<P>
|
|
<DT><CODE>TIOCSLCKTRMIOS</CODE>
|
|
<DD>Sets the locking status of the <CODE>termios</CODE> structure of the terminal.
|
|
<VAR>argp</VAR> points to a <VAR>termios</VAR> structure that contains the new
|
|
flags. The calling task must have superuser privileges.
|
|
<P>
|
|
<DT><CODE>TIOCPKT</CODE>
|
|
<DD>If <VAR>argp</VAR> is 1, it sets the <CODE>packet</CODE> flag in the tty structure,
|
|
otherwise it sets the flag to zero. (What purpose does that serves?)
|
|
<P>
|
|
<DT><CODE>TIOCLINUX</CODE>
|
|
<DD>Linux dependent.
|
|
<P>
|
|
<DT><CODE>TCSBRK</CODE>
|
|
<DD>Waits for the output queue to become empty, then, if <VAR>argp</VAR> is 1,
|
|
sends a break.
|
|
<P>
|
|
<DT><CODE>TCSBRKP</CODE>
|
|
<DD>Same as <CODE>TCSBRK</CODE>?
|
|
</DL>
|
|
<P>
|
|
<H3>RETURN VALUE</H3>
|
|
<P>
|
|
On success zero is returned. On error, -1 is returned and <CODE>errno</CODE> is
|
|
set to one of the following values:
|
|
<P>
|
|
<UL>
|
|
<LI><CODE>EINVAL</CODE>: <VAR>cmd</VAR> or <VAR>argp</VAR> have an invalid value.
|
|
<LI><CODE>ENOTTY</CODE>: <VAR>d</VAR> is not a character special device or the
|
|
request made on <VAR>d</VAR> is not valid for this type of device.
|
|
<LI><CODE>EBADF</CODE>.
|
|
</UL>
|
|
<P>
|
|
<P>Go to the <A HREF="syscalls_16.html" tppabs="http://www.infran.ru/TechInfo/syscalls/syscalls_16.html">previous</A>, <A HREF="syscalls_18.html" tppabs="http://www.infran.ru/TechInfo/syscalls/syscalls_18.html">next</A> section.<P>
|