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 perform a variety of network-related control. The fd argument is a socket descriptor. For non-socket descriptors, the functions 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 specified by the user.

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

• Socket
• Routing table
• ARP table
• Global network parameters
• Interface

Parameters

fdOpen file descriptor that refers to a socket created using socket or accept calls.cmdSelects the control function to be performed..../* arg */Represents additional information that is needed to perform 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 commandDescriptionSIOCATMARKDetermines whether the read pointer is currently pointing to the logical mark in the data stream. 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. Ifatmark is set to 0 on return, (assuming out-of-band data is present on the data stream), the next read returns data sent prior to 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 
SIOCGPGRPSIOCSPGRP 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 commandDescriptionSIOCADDRT 
SIOCDELRTSIOCADDRT 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.SIOUPDROUTEUpdates the routing table using the information 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 commandDescriptionSIOCSARP 
SIOCDARP 
SIOCGARPSIOCSARP 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 commandDescriptionSIOCSNETOPT 
SIOCGNETOPT 
SIOCDNETOPT 
SIOCGNETOPT1SIOCSNETOPT 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 
SIOCDELMTUSIOCGNMTUS 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 commandDescriptionSIOCSIFADDR 
SIOCAIFADDR 
SIOCDIFADDR 
SIOCGIFADDRSIOCSIFADDR 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.

SIOCGIFADDRSGets the list of addresses 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 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). In order 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 
SIOCGIFDSTADDRSIOCSIFDSTADDR sets the point-to-point address for an interface specified in the ifr.ifr_dstaddr field. SIOCGIFDSTADDR gets the point-to-point address associated with an interface. The address is stored in theifr.ifr_dstaddr field on return.

ioctl(fd, cmd, (caddr_t)&ifr, sizeof(struct ifreq));struct ifreq ifr;

cmd

Set to SIOCSIFDSTADDR or SIOCGIFDSTADDR.

SIOCSIFNETMASK 
SIOCGIFNETMASKSIOCSIFNETMASK sets the interface netmask 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 
SIOCGIFBRDADDRSIOCSIFBRDADDR sets the interface broadcast address 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.

SIOCGSIZIFCONFGets the size of memory required to get configuration information for all interfaces returned by SIOCGIFCONF.

ioctl(fd, cmd, (caddr_t)&ifconfsize);int ifconfsize;

SIOCGIFCONFReturns configuration information for all the interfaces 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 ifreqstructure 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 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 
SIOCGIFFLAGSSIOCSIFFLAGS 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, andIFF_MULTICAST flags cannot be changed using ioctl.

SIOCSIFMETRIC 
SIOCGIFMETRICSIOCSIFMETRIC sets the interface metric 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 
SIOCGIFSUBCHANSIOCSIFSUBCHAN sets the subchannel address 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 
SIOCGIFOPTIONSSIOCSIFOPTIONS 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 denoted by IFO_xxx.ioctl commandDescriptionSIOCADDMULTI 
SIOCDELMULTISIOCADDMULTI 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.SIOCGETVIFCNTGets the packet count information for a virtual interface. The information is specified in the sioc_vif_reqstructure.

ioctl (fd, SIOCGETVIFCNT, (caddr_t)&v_req);struct sioc_vif_req  v_req;

SIOCGETSGCNTGets the packet count information for the source group specified. The information is stored in the sioc_sg_reqstructure on return.

ioctl(fd, SIOCGETSGCNT, (caddr_t)&v_req);struct sioc_sg_req v_req;

SIOCSIFMTU 
SIOCGIFMTUSIOCSIFMTU 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 depending on the interface type.

SIOCIFATTACH 
SIOCIFDETACHSIOCIFATTACH 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 
SIOCGIFGIDLISTSIOCSIFGIDLIST 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 theifrg.ifrg_gidlist field indicates whether the specified list of group IDs must be added to or deleted from the gidlistinterface. 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_SARPSIOCIF_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 will be an ARP client or an ARP server for this Logical IP Subnetwork (LIS) based on the flag set in the ifatm_svc_arg structure. 
SIOCIF_ATM_IDLE specifies the idle time limit on the interface.SIOCSISNO 
SIOCGISNOSIOCSISNO sets interface specific network options for an interface. SIOCGISNO gets interface specific network options 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 denoted by ISNO_xxx.SIOCGIFBAUDRATEGets 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 
SIOCLISTIFVIPASIOCADDIFVIPA associates the specified list of interfaces pointed to by ifrv.ifrv_ifname with the virtual interface specified by ifrv.ifrv_name. This 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 pointed to by ifrv.ifrv_ifname, that are associated with the virtual interface specified by ifrv.ifrv_name, using SIOCADDIFVIPA. 
SIOCLISTIFVIPA lists all the interfaces 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.

SIOCSIFADDR6Set or Add an IPv6 address.

ioctl(fd, SIOCSIFADDR6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCGIFADDR6Gets an IPv6 address.

ioctl(fd, SIOCGIFADDR6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCSIFDSTADDR6Set the destination (point-to-point) address for a IPv6 address.

ioctl(fd, SIOCSIFDSTADDR6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCGIFDSTADDR6Get the destination (point-to-point) address for a IPv6 address.

ioctl(fd, SIOCGIFDSTADDR6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCSIFNETMASK6Set the netmask for an IPv6 address as specified in the ifr.ifr_Addr structure.

ioctl(fd, SIOCSIFNETMASK6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCGIFNETMASK6Get the netmask for an IPv6 address as specified in the ifr.ifr_Addr structure.

ioctl(fd, SIOCGIFNETMASK6, (caddr_t)&ifr);struct in6_ifreq ifr;

Note:

The ifr structure can be filled by calling the ioctl function for the SIOCGIFADDR6 command before calling the SIOCGIFNETMASK6 command.

SIOCDIFADDR6Delete an IPv6 address.

ioctl(fd, SIOCDIFADDR6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCFIFADDR6Put an IPv6 address at the beginning of the address list.

ioctl(fd, SIOCFIFADDR6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCAIFADDR6Add or change an IPv6 alias address.

ioctl(fd, SIOCAIFADDR6, (caddr_t)&ifra);struct in6_aliasreq ifra;

SIOCADDANY6Add an IPv6 anycast address.

ioctl(fd, SIOCADDANY6, (caddr_t)&ifra);struct in6_ifreq ifr;

SIOCDELANY6Delete an IPv6 anycast address.

ioctl(fd, SIOCDELANY6, (caddr_t)&ifra);struct in6_ifreq ifr;

SIOCSIFZONE6Set the IPv6 zone ID of an interface at a particular address scope.

ioctl(fd, SIOCSIFZONE6, (caddr_t)&ifrz);struct in6_zonereq ifrz;

SIOCGIFZONE6Get the IPv6 scope zone IDs of an interface.

ioctl(fd, SIOCGIFZONE6, (caddr_t)&ifrz);struct in6_zonereq ifrz;

SIOCSIFADDRORI6Set the configuration origin for an IPv6 address.

ioctl(fd, SIOCSIFADDRORI6, (caddr_t)&ifro);struct ifaddrorigin6 ifro;

SIOCAIFADDR6TAdd or change an IPv6 alias address and type.

ioctl(fd, SIOCAIFADDR6T, (caddr_t)&ifra);struct in6_aliasreq2 ifra;

SIOCGIFADDR6TGet the type of an IPv6 address.

ioctl(fd, SIOCGIFADDR6T, (caddr_t)&ifra);struct in6_aliasreq2 ifra;

SIOCSIFADDRSTATE6Change the state of an IPv6 address.

ioctl(fd, SIOCSIFADDRSTATE6, (caddr_t)&ifra);struct in6_aliasreq2 ifra;

SIOCGIFADDRSTATE6Get the state of an IPv6 address.

ioctl(fd, SIOCGIFADDRSTATE6, (caddr_t)&ifra);struct in6_aliasreq2 ifra;

SIOCGSRCFILTER6Get the IPv6 multicast group source filter for an interface.

ioctl(fd, SIOCGSRCFILTER6, (caddr_t)&ifrgsf);struct group_source_filter_req ifrgsf;

SIOCACLADDR6Add an IPv6 cluster alias address.

ioctl(fd, SIOCACLADDR6, (caddr_t)&ifra);struct in6_aliasreq ifra;

SIOCDCLADDR6Delete an IPv6 cluster address.

ioctl(fd, SIOCDCLADDR6, (caddr_t)&ifr);struct in6_ifreq ifr;

SIOCSIFADDRFLAG6Set address source flag for an IPv6 address.

ioctl(fd, SIOCSIFADDRFLAG6, (caddr_t)&ifra2);struct in6_aliasreq2 ifra2;

SIOCGIFADDRFLAG6Get 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:

EBADFThe file descriptor fd is not a valid open socket file descriptor.EINTRA signal was caught during ioctl operation.EINVALAn 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:

EACCESPermission denied for the specified operation.EADDRNOTAVAILSpecified address not available for interface.EAFNOSUPPORTOperation not supported on sockets.EBUSYResource is busy.EEXISTAn entry or file already exists.EFAULTArgument references an inaccessible memory area.EIOI/O error.ENETUNREACHGateway unreachable.ENOBUFSRouting table overflow.ENOCONNECTNo connection.ENOMEMNot enough memory available.ENOTCONNThe operation is only defined on a connected socket, but the socket was not connected.ENXIODevice does not exist.ESRCHNo such process.

----

====

http://publib.boulder.ibm.com/infocenter/aix/v6r1/index.jsp?topic=%2Fcom.ibm.aix.commtechref%2Fdoc%2Fcommtrf2%2Fioctl_socket_control_operations.htm