ioctl Socket Control Operations

Purpose

Performs network-related control operations.

Syntax

#include <sys/ioctl.h>

int ioctl (fd,  cmd, .../* arg */) 
int  fd;
int  cmd; 
int ...  /* arg */

Description

The socket ioctl commands does various network-related control. The fd argument is a socket descriptor. For non-socket descriptors, the functions that are performed by this call are unspecified.

The cmd argument and an optional third argument (with varying type) are passed to and interpreted by the socket ioctl function to perform an appropriate control operation that is specified by the user.

The socket ioctl control operations can be in the following control operations categories:

Parameters

Item Description
fd Open file descriptor that refers to a socket created by using socket or accept calls.
cmd Selects the control function to be performed.
.../* arg */ Represents information that is required for the requested function. The type of arg depends on the particular control request, but it is either an integer or a pointer to a socket-specific data structure.

Socket Control Operations

The following ioctl commands operate on sockets:
ioctl command Description
SIOCATMARK Determines whether the read pointer is pointing to the logical mark in the DataStream. The logical mark indicates the point at which the out-of-band data is sent. 
ioctl(fd, SIOCATMARK,&atmark);
int atmark;
If atmark is set to 1 on return, the read pointer points to the mark and the next read returns data after the mark. If atmark is set to 0 on return (assuming out-of-band data is present on the DataStream), the next read returns data that is sent before the out-of-band mark.
Note: The out-of-band data is a logically independent data channel that is delivered to the user independently of normal data; in addition, a signal is also sent because of the immediate attention required. Ctrl-C characters are an example.

SIOCSPGRP

SIOCGPGRP

 SIOCSPGRP sets the process group information for a socket. SIOCGPGRP gets the process group ID associated with a socket. 
ioctl (fd, cmd, (int)&pgrp);
int  pgrp;
cmd
Set to SIOCSPGRP or SIOCGPGRP.
pgrp
Specifies the process group ID for the socket.

Routing Table Control Operations

The following ioctl commands operate on the kernel routing table:
ioctl command Description

SIOCADDRT

SIOCDELRT

 SIOCADDRT adds a route entry in the routing table. SIOCDELRT deletes a route entry from the routing table. 
ioctl(fd, cmd, (caddr_t)&route);
struct ortentry route;
cmd
Set to SIOCADDRT or SIOCDELRT.
The route entry information is passed in the ortentry structure.
SIOUPDROUTE Updates the routing table by using the information that is passed in the ifreq structure. 
ioctl (fd, SIOUPDROUTE, (caddr_t)&ifr);
struct ifreq  ifr;
Note: SIOUPDROUTE is available beginning with AIX® 5100-002 (maintenance level 2) and later.

ARP Table Control Operations

The following ioctl commands operate on the kernel ARP table. The net/if_arp.h header file must be included.
ioctl command Description

SIOCSARP

SIOCDARP

SIOCGARP

 SIOCSARP adds or modifies an ARP entry in the ARP table. SIOCDARP deletes an ARP entry from the ARP table. SIOCGARP gets an ARP entry from the ARP table. 
ioctl(fd, cmd, (caddr_t)&ar);
struct arpreq ar;
cmd
Set to SIOCSARP, SIOCDARP, or SIOCGARP.
The ARP entry information is passed in the arpreq structure.

Global Network Parameters Control Operations

The following ioctl commands operate as global network parameters:
ioctl command Description

SIOCSNETOPT

SIOCGNETOPT

SIOCDNETOPT

SIOCGNETOPT1

 SIOCSNETOPT sets the value of a network option. SIOCGNETOPT gets the value of a network option. SIOCDNETOPT sets the default values of a network option. 
ioctl(fd, cmd, (caddr_t)&oreq);
struct optreq oreq;
cmd
Set to SIOCSNETOPT, SIOCGNETOPT, or SIOCDNETOPT.
The network option value is stored in the optreq structure.
SIOCGNETOPT1 gets the current value, default value, and the range of a network option. 
ioctl(fd, SIOCGNETOPT1, (caddr_t)&oreq);
struct optreq1 oreq;
The network option information is stored in the optreq1 structure upon return The optreq and optreq1 structures are defined in net/netopt.h.
Note: SIOCGNETOPT1 is available beginning with AIX 5.2 and later.

SIOCGNMTUS

SIOCGETMTUS

SIOCADDMTU

SIOCDELMTU

 SIOCGNMTUS gets the number of MTUs maintained in the list of common MTUs. SIOCADDMTU adds an MTU in the list of common MTUs. SIOCDELMTU deletes an MTU from the list of common MTUs. 
ioctl(fd, cmd, (caddr_t)&nmtus);
int nmtus;
cmd
Set to SIOCGNMTUS, SIOCADDMTU, or SIOCDELMTU.
SIOCGETMTUS gets the MTUs maintained in the list of common MTUs. 
ioctl(fd, SIOCGETMTUS, (caddr_t)&gm);
struct get_mtus gm;
The get_mtus structure is defined in netinet/in.h.

Interface Control Operations

The following ioctl commands operate on interfaces. The net/if.h header file must be included.
ioctl command Description

SIOCSIFADDR

SIOCAIFADDR

SIOCDIFADDR

SIOCGIFADDR

 SIOCSIFADDR sets an interface address. SIOCAIFADDR adds or changes an interface address. SIOCDIFADDR deletes an interface address. The interface address is specified in the ifr.ifr_addr field. SIOCGIFADDR gets an interface address. The address is returned in the ifr.ifr_addr field. 
ioctl(fd, cmd, (caddr_t)&ifr, sizeof(struct ifreq));
struct ifreq ifr;
cmd
Set to SIOCSIFADDR, SIOCAIFADDR, SIOCDIFADDR, or SIOCGIFADDR.
SIOCGIFADDRS Gets the list of addresses that are associated with an interface. 
ioctl (fd, SIOCGIFADDRS, (caddr_t)ifaddrsp);
struct ifreqaddrs  *ifaddrsp;
The interface name is passed in the ifaddrsp->ifr_name field. The addresses that are associated with the interface are stored in ifaddrsp->ifrasu array on return.
Note: The ifreqaddrs structure contains space for storing only one sockaddr_in/sockaddr_in6 structure (array of one sockaddr_in/sockaddr_in6 element). To get n addresses associated with an interface, the caller of the ioctl command must allocate space for {sizeof (struct ifreqaddrs) + (n * sizeof (struct sockaddr_in)} bytes.
Note: SIOCGIFADDRS is available beginning with AIX 5.3 and later.

SIOCSIFDSTADDR

SIOCGIFDSTADDR

 SIOCSIFDSTADDR sets the point-to-point address for an interface that is specified in the ifr.ifr_dstaddr field. SIOCGIFDSTADDR gets the point-to-point address that is associated with an interface. The address is stored in the ifr.ifr_dstaddr field on return. 
ioctl(fd, cmd, (caddr_t)&ifr, sizeof(struct ifreq));
struct ifreq ifr;
cmd
Set to SIOCSIFDSTADDR or SIOCGIFDSTADDR.

SIOCSIFNETMASK

SIOCGIFNETMASK

 SIOCSIFNETMASK sets the interface netmask that is specified in the ifr.ifr_addr field. SIOCGIFNETMASK gets the interface netmask. 
ioctl(fd, cmd, (caddr_t)&ifr, sizeof(struct ifreq));
struct ifreq ifr;
cmd
Set to SIOCSIFNETMASK or SIOCGIFNETMASK.

SIOCSIFBRDADDR

SIOCGIFBRDADDR

 SIOCSIFBRDADDR sets the interface broadcast address that is specified in the ifr.ifr_broadaddr field. SIOCGIFBRDADDR gets the interface broadcast address. The broadcast address is placed in the ifr.ifr_broadaddr field. 
ioctl(fd, cmd, (caddr_t)&ifr, sizeof(struct ifreq));
struct ifreq ifr;
cmd
Set to SIOCSIFBRDADDR or SIOCGIFBRDADDR.
SIOCGSIZIFCONF Gets the size of memory that is required to get configuration information for all interfaces returned by SIOCGIFCONF. 
ioctl(fd, cmd, (caddr_t)&ifconfsize);
int ifconfsize;
SIOCGIFCONF Returns configuration information for all the interfaces that are configured on the system. 
ioctl(fd, SIOCGIFCONF, (caddr_t)&ifc);
struct ifconf ifc;
The configuration information is returned in a list of ifreq structures pointed to by the ifc.ifc_req field, with one ifreq structure per interface.
Note: The caller of the ioctl command must allocate sufficient space to store the configuration information, returned as a list of ifreq structures for all of the interfaces that are configured on the system. For example, if n interfaces are configured on the system, ifc.ifc_req must point to {n * sizeof (struct ifreq)} bytes of space allocated.
Note: Alternatively, the SIOCGSIZIFCONF ioctl command can be used for this purpose.

SIOCSIFFLAGS

SIOCGIFFLAGS

 SIOCSIFFLAGS sets the interface flags. SIOCGIFFLAGS gets the interface flags. 
ioctl(fd, cmd, (caddr_t)&ifr);
struct ifreq ifr;
Refer to /usr/include/net/if.h for the interface flags, denoted by IFF_xxx.
Note: The IFF_BROADCAST, IFF_POINTTOPOINT, IFF_SIMPLEX, IFF_RUNNING, IFF_OACTIVE, and IFF_MULTICAST flags cannot be changed by using ioctl.

SIOCSIFMETRIC

SIOCGIFMETRIC

 SIOCSIFMETRIC sets the interface metric that is specified in the ifr.ifr_metric field. SIOCGIFMETRIC gets the interface metric. The interface metric is placed in the ifr.ifr_metric field on return. 
ioctl(fd, cmd, (caddr_t)&ifr);
struct ifreq ifr;
cmd
Set to SIOCSIFMETRIC or SIOCGIFMETRIC.

SIOCSIFSUBCHAN

SIOCGIFSUBCHAN

 SIOCSIFSUBCHAN sets the subchannel address that is specified in the ifr.ifr_flags field. SIOCGIFSUBCHAN gets the subchannel address in the ifr.ifr_flags field. 
ioctl(fd, SIOCSIFSUBCHAN, (caddr_t)&ifr);
struct ifreq ifr;

SIOCSIFOPTIONS

SIOCGIFOPTIONS

 SIOCSIFOPTIONS sets the interface options. SIOCGIFOPTIONS gets the interface options. 
ioctl(fd, SIOCSIFOPTIONS, (caddr_t)&ifr);
struct ifreq ifr;
The interface options are stored in the ifr_flags field of the ifreq structure. Refer to /usr/include/net/if.h file for the list of interface options that are denoted by IFO_xxx.
ioctl command Description

SIOCADDMULTI

SIOCDELMULTI

 SIOCADDMULTI adds an address to the list of multicast addresses for an interface. SIOCDELMULTI deletes a multicast address from the list of multicast addresses for an interface. 
ioctl(fd, cmd, (caddr_t)&ifr);
struct ifreq ifr;
cmd
Set to SIOCADDMULTI or SIOCDELMULTI.
The multicast address information is specified in the ifr_addr structure.
SIOCGETVIFCNT Gets the packet count information for a virtual interface. The information is specified in the sioc_vif_req structure. 
ioctl (fd, SIOCGETVIFCNT, (caddr_t)&v_req);
struct sioc_vif_req  v_req;
SIOCGETSGCNT Gets the packet count information for the source group specified. The information is stored in the sioc_sg_req structure on return. 
ioctl(fd, SIOCGETSGCNT, (caddr_t)&v_req);
struct sioc_sg_req v_req;

SIOCSIFMTU

SIOCGIFMTU

 SIOCSIFMTU sets the interface maximum transmission unit (MTU). SIOCGIFMTU gets the interface MTU. 
ioctl(fd, cmd, (caddr_t)&ifr);
struct ifreq ifr;
The MTU value is stored in ifr.ifr_mtu field.
Note: The range of valid values for MTU varies for an interface and is dependent on the interface type.

SIOCIFATTACH

SIOCIFDETACH

 SIOCIFATTACH attaches an interface. This initializes and adds an interface in the network interface list. SIOCIFDETACH detaches an interface broadcast address. This removes the interface from the network interface list. The interface name is specified in the ifr.ifr_name field. 
ioctl(fd, cmd, (caddr_t)&ifr);
struct ifreq ifr;

SIOCSIFGIDLIST

SIOCGIFGIDLIST

 SIOCSIFGIDLIST adds or deletes the list of group IDs specified in the ifrg.ifrg_gidlist field to the gidlist interface. The interface name is specified in the ifrg.ifrg_name field. An operation code, ADD_GRP/DEL_GRP, specified in the ifrg.ifrg_gidlist field indicates whether the specified list of group IDs must be added to or deleted from the gidlist interface. SIOCGIFGIDLIST gets the list of group IDs associated with an interface. The group IDs are placed in the ifrg.ifrg_gidlist field on return. 
ioctl(fd, cmd, (caddr_t)&ifrg);
struct ifgidreq ifrg;

SIOCIF_ATM_UBR

SIOCIF_ATM_SNMPARP

SIOCIF_ATM_DUMPARP

SIOCIF_ATM_IDLE

SIOCIF_ATM_SVC

SIOCIF_ATM_DARP

SIOCIF_ATM_GARP

SIOCIF_ATM_SARP

 SIOCIF_ATM_UBR sets the UBR rate for an ATM interface. SIOCIF_ATM_SNMPARP gets the SNMP ATM ARP entries. SIOCIF_ATM_DUMPARP gets the specified number of ATM ARP entries. SIOCIF_ATM_DARP deletes an ATM ARP entry from the ARP table. SIOCIF_ATM_GARP gets an ATM ARP entry to the ARP table. SIOCIF_ATM_SARP adds an ATM ARP entry. The ARP information is specified in the atm_arpreq structure. SIOCIF_ATM_SVC specifies whether this interface supports Permanent Virtual Circuit (PVC) and Switched Virtual Circuit (SVC) types of virtual connections. It also specifies whether this interface is an ARP client or an ARP server for this Logical IP Subnetwork (LIS) based on the flag that is set in the ifatm_svc_arg structure. SIOCIF_ATM_IDLE specifies the idle time limit on the interface.

SIOCSISNO

SIOCGISNO

 SIOCSISNO sets interface specific network options for an interface. SIOCGISNO gets interface specific network options that are associated with an interface. 
ioctl(fd, cmd, (caddr_t)&ifr);
struct ifreq ifr;
cmd
Set to SIOCSISNO or SIOCGISNO.
The interface-specific network options are stored in ifr.ifr_isno structure. Refer to /usr/include/net/if.h file for the list of interface-specific network options that are denoted by ISNO_xxx.
SIOCGIFBAUDRATE Gets the value of the interface baud rate in the ifr_baudrate field. 
ioctl(fd, SIOCGIFBAUDRATE, (caddr_t)&ifr);
struct ifreq ifr;
The baud rate is stored in the ifr.ifr_baudrate field.

SIOCADDIFVIPA

SIOCDELIFVIPA

SIOCLISTIFVIPA

 SIOCADDIFVIPA associates the specified list of interfaces pointed to by ifrv.ifrv_ifname with the virtual interface specified by ifrv.ifrv_name. This operation causes the source address for all outgoing packets on these interfaces to be set to the virtual interface address. SIOCDELIFVIPA removes the list of specified interfaces that are pointed by ifrv.ifrv_ifname and associated with the virtual interface specified by ifrv.ifrv_name, by using SIOCADDIFVIPA. SIOCLISTIFVIPA lists all the interfaces that are associated with the virtual interface specified by ifrv.ifrv_name. 
ioctl(fd, SIOCADDIFVIPA, (caddr_t)&ifrv);
struct ifvireq ifrv;
The virtual interface information is stored in the ifvireq structure.
Note: These flags operate on a virtual interface only. Also, these flags are available beginning with AIX 5.2 and later.
SIOCSIFADDR6 Set or Add an IPv6 address. 
ioctl(fd, SIOCSIFADDR6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCGIFADDR6 Gets an IPv6 address. 
ioctl(fd, SIOCGIFADDR6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCSIFDSTADDR6 Set the destination (point-to-point) address for a IPv6 address. 
ioctl(fd, SIOCSIFDSTADDR6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCGIFDSTADDR6 Get the destination (point-to-point) address for a IPv6 address. 
ioctl(fd, SIOCGIFDSTADDR6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCSIFNETMASK6 Set the netmask for an IPv6 address. 
ioctl(fd, SIOCSIFNETMASK6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCGIFNETMASK6 Get the netmask for an IPv6 address. 
ioctl(fd, SIOCGIFNETMASK6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCDIFADDR6 Delete an IPv6 address. 
ioctl(fd, SIOCDIFADDR6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCFIFADDR6 Put an IPv6 address at the beginning of the address list. 
ioctl(fd, SIOCFIFADDR6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCAIFADDR6 Add or change an IPv6 alias address. 
ioctl(fd, SIOCAIFADDR6, (caddr_t)&ifra);
struct in6_aliasreq ifra;
SIOCADDANY6 Add an IPv6 anycast address. 
ioctl(fd, SIOCADDANY6, (caddr_t)&ifra);
struct in6_ifreq ifr;
SIOCDELANY6 Delete an IPv6 anycast address. 
ioctl(fd, SIOCDELANY6, (caddr_t)&ifra);
struct in6_ifreq ifr;
SIOCSIFZONE6 Set the IPv6 zone ID of an interface at a particular address scope. 
ioctl(fd, SIOCSIFZONE6, (caddr_t)&ifrz);
struct in6_zonereq ifrz;
SIOCGIFZONE6 Get the IPv6 scope zone IDs of an interface. 
ioctl(fd, SIOCGIFZONE6, (caddr_t)&ifrz);
struct in6_zonereq ifrz;
SIOCSIFADDRORI6 Set the configuration origin for an IPv6 address. 
ioctl(fd, SIOCSIFADDRORI6, (caddr_t)&ifro);
struct ifaddrorigin6 ifro;
SIOCAIFADDR6T Add or change an IPv6 alias address and type. 
ioctl(fd, SIOCAIFADDR6T, (caddr_t)&ifra);
struct in6_aliasreq2 ifra;
SIOCGIFADDR6T Get the type of an IPv6 address. 
ioctl(fd, SIOCGIFADDR6T, (caddr_t)&ifra);
struct in6_aliasreq2 ifra;
SIOCSIFADDRSTATE6 Change the state of an IPv6 address. 
ioctl(fd, SIOCSIFADDRSTATE6, (caddr_t)&ifra);
struct in6_aliasreq2 ifra;
SIOCGIFADDRSTATE6 Get the state of an IPv6 address. 
ioctl(fd, SIOCGIFADDRSTATE6, (caddr_t)&ifra);
struct in6_aliasreq2 ifra;
SIOCGSRCFILTER6 Get the IPv6 multicast group source filter for an interface. 
ioctl(fd, SIOCGSRCFILTER6, (caddr_t)&ifrgsf);
struct group_source_filter_req ifrgsf;
SIOCACLADDR6 Add an IPv6 cluster alias address. 
ioctl(fd, SIOCACLADDR6, (caddr_t)&ifra);
struct in6_aliasreq ifra;
SIOCDCLADDR6 Delete an IPv6 cluster address. 
ioctl(fd, SIOCDCLADDR6, (caddr_t)&ifr);
struct in6_ifreq ifr;
SIOCSIFADDRFLAG6 Set address source flag for an IPv6 address. 
ioctl(fd, SIOCSIFADDRFLAG6, (caddr_t)&ifra2);
struct in6_aliasreq2 ifra2;
SIOCGIFADDRFLAG6 Get address source flag for an IPv6 address. 
ioctl(fd, SIOCGIFADDRFLAG6, (caddr_t)&ifra2);
struct in6_aliasreq2 ifra2;

Return Values

Upon successful completion, ioctl returns 0. Otherwise, it returns -1 and sets errno to indicate the error.

Error Codes

The ioctl commands fail under the following general conditions:
Item Description
EBADF The file descriptor fd is not a valid open socket file descriptor.
EINTR A signal was caught during ioctl operation.
EINVAL An invalid command or argument was specified.
If the underlying operation specified by the ioctl command cmd failed, ioctl fails with one of the following error codes:
Item Description
EACCES Permission that is denied for the specified operation.
EADDRNOTAVAIL Specified address not available for interface.
EAFNOSUPPORT Operation that is not supported on sockets.
EBUSY Resource is busy.
EEXIST An entry or file exists.
EFAULT Argument references an inaccessible memory area.
EIO Input/Output error.
ENETUNREACH Gateway unreachable.
ENOBUFS Routing table overflow.
ENOCONNECT No connection.
ENOMEM Not enough memory available.
ENOTCONN The operation is only defined on a connected socket, but the socket was not connected.
ENXIO Device does not exist.
ESRCH No such process.