NAME

sockio − socket ioctl commands

SYNOPSIS

#include <ioctl.h>
int ioctl (fildes, command, arg)
int fildes, command;
int ∗arg;
or
struct ifconf ∗arg;
or
struct ifreq ∗arg;

DESCRIPTION

Socket [see intro(4N) and socket(2)] ioctl commands are a subset of ioctl(2) system calls which perform a variety of control functions on sockets. 

fildes is an open file descriptor that refers to a socket.  command determines the control function to be performed as described below.  arg represents additional information that is needed by this command.  The type of arg depends upon the command, but it is generally an integer pointer or a pointer to a command-specific data structure (ifreq or ifconf structure). 

COMMAND FUNCTIONS

The following ioctl commands use args of type integer pointer and are applicable to all sockets:

FIOASYNC (∗) Set or clear asynchronous I/O functionality on the socket referred to by fildes depending on the value referred to by arg.  This command can also be used on terminal devices.  If the field referred to by arg is set to zero, the socket is set to synchronous I/O mode.  The default I/O mode for Internet sockets is synchronous.  In synchronous I/O mode, the process or process group associated with the socket will not receive any special notification when the socket has data available to read.  If the field referred to by arg is nonzero, the socket is set to asynchronous I/O mode.  In asynchronous mode, the process or process group associated with the socket will receive notification when the socket has data available to read by means of a SIGIO signal.  When a process is blocked on a select(2), SIGIO will also result when the socket goes from unwriteable to writeable. 

FIOGETOWN (∗)
Retrieve the ID of the process/process group associated with the socket referred to by fildes and return it in the field referred to by arg.  This call may also be used on terminal devices.  Its functionality is identical to SIOCGPGRP.  See the information below on SIOCGPGRP for operation of this command. 

FIONBIO (∗) Set or clear non-blocking I/O functionality on the socket referred to by fildes depending on the value of the field referred to by arg.  Use of this command is equivalent to the fcntl(2) call with O_NONBLOCK set.  It may also be used on terminal devices.  If the field referred to by arg is set to zero, the socket is set to blocking I/O mode.  This is the default mode for all sockets.  A process issuing a system call on a blocking socket will pend on that call until the required processing associated with it is complete.  If the field referred to by arg contains a nonzero value, the socket will be set to non-blocking I/O mode.  A process issuing a system call on a non-blocking socket will return without pending on the completion of the required processing for that call.  Under certain cases, the processing of a system call on a non-blocking mode socket may be incomplete, in which case the call will return -1 and errno set to [EAGAIN].  A user process may then use the select(2) call to determine the completion of the system call processing. 

FIONREAD (∗)
Retrieve the number of bytes of data available to be read on the socket referred to by fildes.  This command may be used on terminal devices.  The result is returned in the field referred to by arg. 

FIOSETOWN (∗)
Set the ID of the process or process group associated with the socket referred to by fildes to the value of the field referred to by arg.  This command may be used on terminal devices, but its behavior will be different (see termio(7), termios(7), or sgtty(7)).  When used on sockets, its functionality is identical to the SIOCSPGRP command described below. 

SIOCGPGRP (∗)
Retrieve the ID of the process/process group associated with the socket referred to by fildes and place it in the field referred to by arg.  The signed value of the field referred to by arg also indicates the recipient of any signals associated with the socket.  This call may only be used on sockets.  If the field referred to by arg contains a positive number, signals associated with the socket are being directed to the process identified by the absolute value of that number.  If the field referred to by arg contains a negative number, signals associated with the socket are being directed to the process group identified by the absolute value of that number.  If the field referred to by arg contains a zero, signals associated with the socket are not being directed to any process or process group. 

SIOCSPGRP (∗)
Set the ownership of the socket referred to by fildes to the process/process group ID contained in the field referred to by arg.  The signed value placed in the field referred to by arg will also indicate whether the process or process group to be associated with the socket will be the recipient of any signals.  If the field referred to by arg contains a positive number, signals will be directed to the process identified by the absolute value of that number.  If the field referred to by arg contains a negative number, signals will be directed to the process group identified by the absolute value of that number.  If the field referred to by arg contains a zero, signals associated with the socket will be prevented from being sent to any process or process group.  By default, ownership of a socket will not be associated with any process or process group.

Each network in a system corresponds to a path through which messages may be sent and received.  A network interface usually has a hardware device associated with it, though some such as the loopback interface (lo(7C)) do not.  At boot time each interface which has underlying hardware support makes itself known to the system during the autoconfiguration process.  During this process, each interface acquires an address.  This address along with specific information about the interface is stored in an ifreq structure.  For each interface there is a corresponding ifreq structure and each is placed within a system array known as the interface configuration list.  For use by application programs, the configuration list can be organized and placed within an ifconf structure.  Both structures are defined in <net/if.h>.  The ifconf structure is defined as follows:

structifconf {
intifc_len;        /∗ size of associated buffer ∗/
union {
caddr_tifcu_buf;
structifreq ∗ifcu_req;
} ifc_ifcu;
#defineifc_bufifc_ifcu.ifcu_buf  /∗ buffer address ∗/
#defineifc_reqifc_ifcu.ifcu_req  /∗ array of structures returned ∗/
};

An ifreq structure entry located in the configuration list would be defined as follows:

structifreq {
charifr_name[16];/∗ name of interface (e.g. "ec0") ∗/
union {
structsockaddr ifru_addr;
structsockaddr ifru_dstaddr;
structsockaddr ifru_broadaddr;
shortifru_flags;
intifru_metric;
caddr_tifru_data;
} ifr_ifru;
#define ifr_addr       ifr_ifru.ifru_addr    /∗ address ∗/
#define ifr_dstaddr    ifr_ifru.ifru_dstaddr /∗ other end of p-to-p link ∗/
#define ifr_broadaddr  ifr_ifru.ifru_broadaddr /∗ broadcast address ∗/
#define ifr_flags      ifr_ifru.ifru_flags   /∗ flags ∗/
#define ifr_metric     ifr_ifru.ifru_metric  /∗ metric ∗/
#define ifr_data       ifr_ifru.ifru_data    /∗ for use by the interface ∗/
};

The ifr_name field contains the interface name.  The size of this field is the maximum size of an interface name, and it consists of a null-terminated ASCII string.  The null byte is counted as part of the size of the name.  The ifr_metric field contains the number of "hops" or nodes which must be passed through in order to reach the interface.  The ifr_flags field provides information on the state of a network interface by the inclusive ORing or zero or more of the following flags located in <net/if.h>:

IFF_UP 0x1 /∗ Check a single bit to know if interface is up ∗/
IFF_BROADCAST 0x2  /∗ Broadcast address valid ∗/
IFF_DEBUG 0x4 /∗ Turn on debugging ∗/
IFF_LOOPBACK 0x8  /∗ Interface associated with loop-back network ∗/
IFF_POINTTOPOINT 0x10  /∗ Interface is point-to-point link ∗/
IFF_NOTRAILERS 0x20  /∗ Avoid use of trailers ∗/
IFF_RUNNING 0x40 /∗ Interface associated with functional network device ∗/
IFF_NOARP 0x80 /∗ No address resolution protocol ∗/
IFF_PROMISC 0x100 /∗ Reserved:  Receive all packets ∗/
IFF_ALLMULTI 0x200 /∗ Reserved:  Receive all multicast packets ∗/
IFF_NOREDIRECT 0x400  /∗ LAN/SX:  No ICMP redirect allowed ∗/

The following ioctl command uses an arg of type pointer to an ifconf structure and is applicable only to Internet sockets:

SIOCGIFCONF (∗)
Get the system interface configuration list.  The command returns a pointer referencing a user defined iconf structure containing a list composed of one ifreq structure for every interface used by the system.  A calling program should initialize the ifc_ifcu.ifcu_req field of the ifconf structure to reference an array of ifreq structures.  The size of the array, in bytes, will be reflected in the value placed in the ifc_len field by the calling program.  This size should reflect the number of elements in the array (ifc_len/sizeof(struct ifreq)).  The command will fill the in the array referenced by the ifc_ifcu.ifcu_req field.  The information about each interface is filled in the ifr_name field and the ifru_addr field of the ifr_ifru union.  If the requested size of the array is smaller than the actual size of the configuration list, then the command will fill the array with as many ifreq structures as it can starting at the beginning of the configuration list.  If the requested size of the array is equal to or larger than the actual configuration list size, the array will be filled with all elements from the list and any remaining space left over in the user-defined array will be remain untouched.  The if_len field will be updated to reflect the amount of space, in bytes, left unmodified in the user array referenced by the ifc_ifcu.ifcu_req field. 

The following ioctl commands uses args of type pointer to an ifreq structure and are applicable only to Internet sockets:

SIOCATMARK (∗)
Notify socket owner that TCP Urgent data has been received.  The arrival of Urgent data is signaled to the process or process group associated with the socket referred by fildes by the means of a SIGURG signal.  A nonzero value returned in arg indicates that the file pointer is at the location of the urgent octect.  If this data has been sent out-of-band, the next octect would be the octect following the urgent octect.  If not, the next octect read will be the urgent octect. 

SIOCGIFADDR (∗)
Get the interface address for a particular network interface. The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface.  Upon successful completion, the system will return the Internet address of the interface in the ifr_ifru.ifru_addr field. 

SIOCGIFBRDADDR (∗)
Get the interface broadcast address for a particular network interface. The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface.  The IFF_BROADCAST flag must be set in the ifr_ifru.ifru_flags fields, otherwise the command will fail and errno will be set to [EINVAL].  Upon successful completion, the system will return the Internet Broadcast address of the interface in the ifr_ifru.ifru_broadcast field. 

SIOCGIFDSTADDR (∗)
Get the interface address associated with the remote host on a point-to-point network interface. The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface.  The IFF_POINTOPOINT flag must be set in the ifr_ifru.ifru_flags fields, otherwise the command will fail and errno will be set to [EINVAL].  Upon successful completion, the system will return the Internet address of the interface in the ifr_ifru.ifru_dstaddr field. 

SIOCGIFFLAGS (∗)
Get the interface flags associated with a particular network interface. The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface.  Upon successful completion, the system will return the flags for the interface in the ifr_ifru.ifru_flags field.  If the desired interface does not exist, the call will return -1 and errno will be set to [ENXIO]. 

SIOCGIFMETRIC (∗)
Get the metric associated with a particular network interface. The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface.  Upon successful completion, the system will return the metric for the interface in the ifr_ifru.ifru_metric field.  If the desired interface does not exist, the call will return -1 and errno will be set to [ENXIO]. 

SIOCGIFNETMASK (∗)
Get the Internet Network Mask associated with a particular network interface.  The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface.  Upon successful completion, the system will return the Internet Network Mask for the interface in the ifr_ifru.ifru_addr field. 

SIOCSIFADDR Set the interface address associated with a particular network interface.  Use of this command is restricted to root or the system super user.  Attempts by any other user will result in the call returning -1 and errno to be set to [EPERM].  The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface as well as the address to be set in the ifr_ifru.ifru_addr field.  Upon successful completion, the system will set the address for the interface. 

SIOCSIFBRDADDR
Set the interface broadcast address for a particular network interface. Use of this command is restricted to root or the system super user.  Attempts by any other user will result in the call returning -1 and errno to be set to [EPERM].  The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface as well as the destination address to be set in the ifr_ifru.ifru_dstaddr field.  The IFF_BROADCAST flag must be set in the ifr_ifru.ifru_flags field, otherwise the command will fail and errno will be set to [EINVAL].  Upon successful Upon successful completion, the system will set the destination address for the interface. 

SIOCSIFDSTADDR
Set the interface address associated with the remote host on a point-to-point network interface. Use of this command is restricted to root or the system super user.  Attempts by any other user will result in the call returning -1 and errno to be set to [EPERM].  The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface as well as the destination address to be set in the ifr_ifru.ifru_dstaddr field.  The IFF_POINTOPOINT flag must be set in the ifr_ifru.ifru_flags field, otherwise the command will fail and errno will be set to [EINVAL].  Upon successful completion, the system will set the destination address for the interface. 

SIOCSIFFLAGS
Set the interface flags associated with a particular network interface.  Use of this command is restricted to root or the system super user.  Attempts by any other user will result in the call returning -1 and errno to be set to [EPERM].  The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface as well as the flags to be set in the ifr_ifru.ifru_flags field.  Upon successful completion, the system will set the flags for the interface.  If the interface is marked down, any processes currently routing packets through the interface are notified.  If the interface does not exist, the call will return -1 and errno will be set to [ENXIO]. 

SIOCSIFMETRIC
Set the metric associated with a particular network interface.  Use of this command is restricted to root or the system super user.  Attempts by any other user will result in the call returning -1 and errno to be set to [EPERM].  The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface as well as the metric to be set in the ifr_ifru.ifru_metric field.  Upon successful completion, the system will set the metric for the interface.  If the interface does not exist, the call will return -1 and errno will be set to [ENXIO]. 

SIOCSIFNETMASK
Set the Internet Network Mask associated with a particular network interface.  Use of this command is restricted to root or the system super user.  Attempts by any other user will result in the call returning -1 and errno to be set to [EPERM].  The ifr_name field of the ifreq structure referenced by arg should be initialized by the calling program for the desired interface as well as the Internet Network Mask to be set in the ifr_ifru.ifru_addr field.  Upon successful completion of the command the system will set the Internet Network Mask for the interface in the ifr_ifru.ifru_addr field. 

NOTE

The commands listed above which are proceeded by (∗) indicate those socket ioctl commands which are outlined in the 88open’s Binary Compatibility Standard Networking Supplement (BCSNS) and Object Compatibility Standard Networking Supplement (OCSNS).  OCSNS-defined functions may be accessed by passing OCS options to cc(1) and ld(1). 

SEE ALSO

accept(2), bind(2), close(2), connect(2), fchmod(2), fchown(2), fcntl(2), getpeername(2), getsockname(2), getsockopt(2), intro(2), ioctl(2), listen(2), lseek(2), open(2), read(2), readv(2), recv(2), recvfrom(2), recvmsg(2), select(2), send(2), sendmsg(2), sendto(2), setsockopt(2), shutdown(2), signal(2), socket(2), stat(2), write(2), and writev(2) in the CX/UX Programmer’s Reference Manual, and intro(4N) in the CX/UX Networking Reference Manual. 

DIAGNOSTICS

Unless specified otherwise above, the return value from ioctl is 0 upon success and -1 upon failure with errno set. 

CX/UX Administrator’s Reference