TABLE OF CONTENTS bsdsocket.library/-icmp- bsdsocket.library/-inet- bsdsocket.library/-ip- bsdsocket.library/-networking- bsdsocket.library/-route- bsdsocket.library/-tcp- bsdsocket.library/-udp- bsdsocket.library/AbortInterfaceConfig bsdsocket.library/accept bsdsocket.library/AddDomainNameServer bsdsocket.library/AddInterfaceTagList bsdsocket.library/AddNetMonitorHookTagList bsdsocket.library/AddRouteTagList bsdsocket.library/BeginInterfaceConfig bsdsocket.library/bind bsdsocket.library/bpf_close bsdsocket.library/bpf_data_waiting bsdsocket.library/bpf_ioctl bsdsocket.library/bpf_open bsdsocket.library/bpf_read bsdsocket.library/bpf_set_interrupt_mask bsdsocket.library/bpf_set_notify_mask bsdsocket.library/bpf_write bsdsocket.library/ChangeRoadshowData bsdsocket.library/CloseSocket bsdsocket.library/ConfigureInterfaceTagList bsdsocket.library/connect bsdsocket.library/CreateAddrAllocMessageA bsdsocket.library/DeleteAddrAllocMessage bsdsocket.library/DeleteRouteTagList bsdsocket.library/Dup2Socket bsdsocket.library/endnetent bsdsocket.library/endprotoent bsdsocket.library/endservent bsdsocket.library/Errno bsdsocket.library/FreeRouteInfo bsdsocket.library/GetDefaultDomainName bsdsocket.library/getdtablesize bsdsocket.library/gethostbyaddr bsdsocket.library/gethostbyname bsdsocket.library/gethostid bsdsocket.library/gethostname bsdsocket.library/getnetbyaddr bsdsocket.library/getnetbyname bsdsocket.library/getnetent bsdsocket.library/GetNetworkStatistics bsdsocket.library/getpeername bsdsocket.library/getprotobyname bsdsocket.library/getprotobynumber bsdsocket.library/getprotoent bsdsocket.library/GetRouteInfo bsdsocket.library/getservbyname bsdsocket.library/getservbyport bsdsocket.library/getservent bsdsocket.library/GetSocketEvents bsdsocket.library/getsockname bsdsocket.library/getsockopt bsdsocket.library/In_CanForward bsdsocket.library/In_LocalAddr bsdsocket.library/inet_addr bsdsocket.library/inet_aton bsdsocket.library/Inet_LnaOf bsdsocket.library/Inet_MakeAddr bsdsocket.library/Inet_NetOf bsdsocket.library/inet_network bsdsocket.library/Inet_NtoA bsdsocket.library/inet_ntop bsdsocket.library/inet_pton bsdsocket.library/IoctlSocket bsdsocket.library/listen bsdsocket.library/mbuf_adj bsdsocket.library/mbuf_cat bsdsocket.library/mbuf_copyback bsdsocket.library/mbuf_copydata bsdsocket.library/mbuf_copym bsdsocket.library/mbuf_free bsdsocket.library/mbuf_freem bsdsocket.library/mbuf_get bsdsocket.library/mbuf_gethdr bsdsocket.library/mbuf_prepend bsdsocket.library/mbuf_pullup bsdsocket.library/ObtainDomainNameServerList bsdsocket.library/ObtainInterfaceList bsdsocket.library/ObtainRoadshowData bsdsocket.library/ObtainServerSocket bsdsocket.library/ObtainSocket bsdsocket.library/OpenLibrary bsdsocket.library/ProcessIsServer bsdsocket.library/QueryInterfaceTagList bsdsocket.library/recv bsdsocket.library/recvfrom bsdsocket.library/recvmsg bsdsocket.library/ReleaseCopyOfSocket bsdsocket.library/ReleaseDomainNameServerList bsdsocket.library/ReleaseInterfaceList bsdsocket.library/ReleaseRoadshowData bsdsocket.library/ReleaseSocket bsdsocket.library/RemoveDomainNameServer bsdsocket.library/RemoveInterface bsdsocket.library/RemoveNetMonitorHook bsdsocket.library/send bsdsocket.library/sendmsg bsdsocket.library/sendto bsdsocket.library/SetDefaultDomainName bsdsocket.library/SetErrnoPtr bsdsocket.library/setnetent bsdsocket.library/setprotoent bsdsocket.library/setservent bsdsocket.library/SetSocketSignals bsdsocket.library/setsockopt bsdsocket.library/shutdown bsdsocket.library/socket bsdsocket.library/SocketBaseTagList bsdsocket.library/vsyslog bsdsocket.library/WaitSelect bsdsocket.library/-icmp- bsdsocket.library/-icmp- NAME icmp - Internet Control Message Protocol SYNOPSIS #include #include FUNCTION ICMP is the error and control message protocol used by IP and the Internet protocol family. It may be accessed through a ``raw socket'' for network monitoring and diagnostic functions. The proto parameter to the socket call to create an ICMP socket is obtained from getprotobyname(). ICMP sockets are connectionless, and are normally used with the sendto and recvfrom calls, though the connect() call may also be used to fix the destination for future packets (in which case the recv() and send() system calls may be used). Outgoing packets automatically have an IP header prepended to them (based on the destination address). Incoming packets are received with the IP header and options intact. ERRORS A socket operation may fail with one of the following errors returned: [EISCONN] When trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected. [ENOTCONN] When trying to send a datagram, but no destination address is specified, and the socket hasn't been connected. [ENOBUFS] When the system runs out of memory for an internal data structure. [EADDRNOTAVAIL] When an attempt is made to create a socket with a network address for which no network interface exists. SEE ALSO send(), recv(), inet, ip bsdsocket.library/-inet- bsdsocket.library/-inet- NAME inet - Internet protocol family SYNOPSIS #include #include FUNCTION The Internet protocol family is a collection of protocols layered atop the Internet Protocol (IP) transport layer, and utilizing the Internet address format. The Internet family provides protocol support for the SOCK_STREAM, SOCK_DGRAM, and SOCK_RAW socket types; the SOCK_RAW interface provides access to the IP protocol. ADDRESSING Internet addresses are four byte quantities, stored in network standard format. The include file defines this address as a discriminated union. Sockets bound to the Internet protocol family utilize the following addressing structure, struct sockaddr_in { short sin_family; u_short sin_port; struct in_addr sin_addr; char sin_zero[8]; }; Sockets may be created with the local address INADDR_ANY to effect ``wildcard'' matching on incoming messages. The address in a connect() or sendto() call may be given as INADDR_ANY to mean ``this host''. The distinguished address INADDR_BROADCAST is allowed as a shorthand for the broadcast address on the primary network if the first network configured supports broadcast. PROTOCOLS The Internet protocol family is comprised of the IP transport protocol, Internet Control Message Protocol (ICMP), Transmission Control Protocol (TCP), and User Datagram Protocol (UDP). TCP is used to support the SOCK_STREAM abstraction while UDP is used to support the SOCK_DGRAM abstraction. A raw interface to IP is available by creating an Internet socket of type SOCK_RAW. The ICMP message protocol is accessible from a raw socket. The 32-bit Internet address contains both network and host parts. It is frequency-encoded; the most-significant bit is clear in Class A addresses, in which the high-order 8 bits are the network number. Class B addresses use the high-order 16 bits as the network field, and Class C addresses have a 24-bit network part. Sites with a cluster of local networks and a connection to the Internet may chose to use a single network number for the cluster; this is done by using subnet addressing. The local (host) portion of the address is further subdivided into subnet and host parts. Within a subnet, each subnet appears to be an individual network; externally, the entire cluster appears to be a single, uniform network requiring only a single routing entry. Subnet addressing is enabled and examined by the following IoctlSocket() commands on a datagram socket in the Internet domain; they have the same form as the SIOCIFADDR command. SIOCSIFNETMASK Set interface network mask. The network mask defines the network part of the address; if it contains more of the address than the address type would indicate, then subnets are in use. SIOCGIFNETMASK Get interface network mask. bsdsocket.library/-ip- bsdsocket.library/-ip- NAME ip - Internet Protocol SYNOPSIS #include #include int socket(AF_INET, SOCK_RAW, proto); FUNCTION IP is the transport layer protocol used by the Internet protocol family. Options may be set at the IP level when using higher-level protocols that are based on IP (such as TCP and UDP). It may also be accessed through a ``raw socket'' when developing new protocols, or special-purpose applications. There are several IP-level setsockopt()/getsockopt() options. IP_OPTIONS may be used to provide IP options to be transmitted in the IP header of each outgoing packet or to examine the header options on incoming packets. IP options may be used with any socket type in the Internet family. The format of IP options to be sent is that specified by the IP protocol specification (RFC-791), with one exception: the list of addresses for Source Route options must include the first-hop gateway at the beginning of the list of gateways. The first-hop gateway address will be extracted from the option list and the size adjusted accordingly before use. To disable previously specified options, use a zero-length buffer: setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); IP_TOS and IP_TTL may be used to set the type-of-service and time-to-live fields in the IP header for SOCK_STREAM and SOCK_DGRAM sockets. For example, int tos = IPTOS_LOWDELAY; /* see */ setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); int ttl = 60; /* max = 255 */ setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); If the IP_RECVDSTADDR option is enabled on a SOCK_DGRAM socket, the recvmsg call will return the destination IP address for a UDP datagram. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by the IP address. The cmsghdr fields have the following values: cmsg_len = sizeof(struct in_addr) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVDSTADDR Multicast Options: IP multicasting is supported only on AF_INET sockets of type SOCK_DGRAM and SOCK_RAW, and only on networks where the interface driver supports multicasting. The IP_MULTICAST_TTL option changes the time-to-live (TTL) for outgoing multicast datagrams in order to control the scope of the multicasts: u_char ttl; /* range: 0 to 255, default = 1 */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); Datagrams with a TTL of 1 are not forwarded beyond the local network. Multicast datagrams with a TTL of 0 will not be transmitted on any network, but may be delivered locally if the sending host belongs to the destination group and if multicast loopback has not been disabled on the sending socket (see below). Multicast datagrams with TTL greater than 1 may be forwarded to other networks if a multicast router is attached to the local network. For hosts with multiple interfaces, each multicast transmission is sent from the primary network interface. The IP_MULTICAST_IF option overrides the default for subsequent transmissions from a given socket: struct in_addr addr; setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); where "addr" is the local IP address of the desired interface or INADDR_ANY to specify the default interface. An interface's local IP address and multicast capability can be obtained via the SIOCGIFCONF and SIOCGIFFLAGS ioctls. Normal applications should not need to use this option. If a multicast datagram is sent to a group to which the sending host itself belongs (on the outgoing interface), a copy of the datagram is, by default, looped back by the IP layer for local delivery. The IP_MULTICAST_LOOP option gives the sender explicit control over whether or not subsequent datagrams are looped back: u_char loop; /* 0 = disable, 1 = enable (default) */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); This option improves performance for applications that may have no more than one instance on a single host (such as a router demon), by eliminating the overhead of receiving their own transmissions. It should generally not be used by applications for which there may be more than one instance on a single host (such as a conferencing program) or for which the sender does not belong to the destination group (such as a time querying program). A multicast datagram sent with an initial TTL greater than 1 may be delivered to the sending host on a different interface from that on which it was sent, if the host belongs to the destination group on that other interface. The loopback control option has no effect on such delivery. A host must become a member of a multicast group before it can receive datagrams sent to the group. To join a multicast group, use the IP_ADD_MEMBERSHIP option: struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); where mreq is the following structure: struct ip_mreq { struct in_addr imr_multiaddr; /* multicast group to join */ struct in_addr imr_interface; /* interface to join on */ } imr_interface should be INADDR_ANY to choose the default multicast interface, or the IP address of a particular multicast-capable interface if the host is multihomed. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. Up to IP_MAX_MEMBERSHIPS (currently 20) memberships may be added on a single socket. To drop a membership, use: struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); where mreq contains the same values as used to add the membership. Memberships are dropped when the socket is closed or the process exits. Raw IP Sockets: Raw IP sockets are connectionless, and are normally used with the sendto and recvfrom calls, though the connect() call may also be used to fix the destination for future packets (in which case the recv() and send() system calls may be used). If proto is 0, the default protocol IPPROTO_RAW is used for outgoing packets, and only incoming packets destined for that protocol are received. If proto is non-zero, that protocol number will be used on outgoing packets and to filter incoming packets. Outgoing packets automatically have an IP header prepended to them (based on the destination address and the protocol number the socket is created with), unless the IP_HDRINCL option has been set. Incoming packets are received with IP header and options intact. IP_HDRINCL indicates the complete IP header is included with the data and may be used only with the SOCK_RAW type. #include int hincl = 1; /* 1 = on, 0 = off */ setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); Unlike previous BSD releases, the program must set all the fields of the IP header, including the following: ip->ip_v = IPVERSION; ip->ip_hl = hlen / 4; ip->ip_id = 0; /* 0 means kernel set appropriate value */ ip->ip_off = offset; If the header source address is set to INADDR_ANY, the kernel will choose an appropriate address. ERRORS A socket operation may fail with one of the following errors returned: [EISCONN] When trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected. [ENOTCONN] When trying to send a datagram, but no destination address is specified, and the socket hasn't been connected. [ENOBUFS] When the system runs out of memory for an internal data structure. [EADDRNOTAVAIL] When an attempt is made to create a socket with a network address for which no network interface exists. [EACESS] register When an attempt is made to create a raw IP socket by a register non-privileged process. The following errors specific to IP may occur when setting or getting IP options: [EINVAL] An unknown socket option name was given. [EINVAL] The IP option field was improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided. SEE ALSO getsockopt(), send(), recv(), icmp, inet bsdsocket.library/-networking- bsdsocket.library/-networking- NAME networking - introduction to networking facilities SYNOPSIS #include #include #include This section is a general introduction to the networking facilities available in the system. Documentation is broken up into three areas: protocol families (domains), protocols, and network interfaces. All network protocols are associated with a specific protocol family. A protocol family provides basic services to the protocol implementation to allow it to function within a specific network environment. These services may include packet fragmentation and reassembly, routing, addressing, and basic transport. A protocol family may support multiple methods of addressing, though the current protocol implementations do not. A protocol family is normally comprised of a number of protocols, one per socket() type. It is not required that a protocol family support all socket types. A protocol family may contain multiple protocols supporting the same socket abstraction. A protocol supports one of the socket abstractions detailed in socket(). A specific protocol may be accessed either by creating a socket of the appropriate type and protocol family, or by requesting the protocol explicitly when creating a socket. Protocols normally accept only one type of address format, usually determined by the addressing structure inherent in the design of the protocol family/network architecture. Certain semantics of the basic socket abstractions are protocol specific. All protocols are expected to support the basic model for their particular socket type, but may, in addition, provide non-standard facilities or extensions to a mechanism. For example, a protocol supporting the SOCK_STREAM abstraction may allow more than one byte of out-of-band data to be transmitted per out-of-band message. A network interface is similar to a device interface. Network interfaces comprise the lowest layer of the networking subsystem, interacting with the actual transport hardware. An interface may support one or more protocol families and/or address formats. ADDRESSING Associated with each protocol family is an address format. All network address adhere to a general structure, called a sockaddr, described below. However, each protocol imposes finer and more specific structure, generally renaming the variant, which is discussed in the protocol family manual page alluded to above. struct sockaddr { u_char sa_len; u_char sa_family; char sa_data[14]; }; The field sa_len contains the total length of the of the structure, which may exceed 16 bytes. The following address value for sa_family is known to the system: #define AF_INET 2 /* internetwork: UDP, TCP, etc. */ INTERFACES Each network interface 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 certain interfaces such as the loopback interface, do not. The following IoctlSocket() calls may be used to manipulate network interfaces. The ioctl is made on a socket (typically of type SOCK_DGRAM) in the desired domain. Most of the requests supported in earlier releases take an ifreq structure as its parameter. This structure has the form struct ifreq { #define IFNAMSIZ 16 char ifr_name[IFNAMSIZE]; /* if name, e.g. "en0" */ union { struct sockaddr ifru_addr; struct sockaddr ifru_dstaddr; struct sockaddr ifru_broadaddr; short ifru_flags; int ifru_metric; caddr_t ifru_data; } ifr_ifru; #define ifr_addr ifr_ifru.ifru_addr /* address */ #define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of point to point 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 interface */ }; Calls which are now deprecated are: SIOCSIFADDR Set interface address for protocol family. Following the address assignment, the ``initialization'' routine for the interface is called. SIOCSIFDSTADDR Set point to point address for protocol family and interface. SIOCSIFBRDADDR Set broadcast address for protocol family and interface. ioctl requests to obtain addresses and requests both to set and retrieve other data are still fully supported and use the ifreq structure. SIOCGIFADDR Get interface address for protocol family. SIOCGIFDSTADDR Get point to point address for protocol family and interface. SIOCGIFBRDADDR Get broadcast address for protocol family and interface. SIOCSIFFLAGS Set interface flags field. If the interface is marked down, any processes currently routing packets through the interface are notified; some interfaces may be reset so that incoming packets are no longer received. When marked up again, the interface is reinitialized. SIOCGIFFLAGS Get interface flags. SIOCSIFMETRIC Set interface routing metric. The metric is used only by user-level routers. SIOCGIFMETRIC Get interface metric. There are two requests that make use of a new structure: SIOCAIFADDR An interface may have more than one address associated with it in some protocols. This request provides a means to add additional addresses (or modify characteristics of the primary address if the default address for the address family is specified). Rather than making separate calls to set destination or broadcast addresses, or network masks (now an integral feature of multiple protocols) a separate structure is used to specify all three facets simultaneously (see below). One would use a slightly tailored version of this struct specific to each family (replacing each sockaddr by one of the family-specific type). Where the sockaddr itself is larger than the default size, one needs to modify the ioctl identifier itself to include the total size, as described in IoctlSocket(). SIOCDIFADDR This requests deletes the specified address from the list associated with an interface. It also uses the if_aliasreq structure to allow for the possibility of protocols allowing multiple masks or destination addresses, and also adopts the convention that specification of the default address means to delete the first address for the interface belonging to the address family in which the original socket was opened. SIOCGIFCONF Get interface configuration list. This request takes an ifconf structure (see below) as a value-result parameter. The ifc_len field should be initially set to the size of the buffer pointed to by ifc_buf. On return it will contain the length, in bytes, of the configuration list. /* * Structure used in SIOCAIFCONF request. */ struct ifaliasreq { char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ struct sockaddr ifra_addr; struct sockaddr ifra_broadaddr; struct sockaddr ifra_mask; }; /* * Structure used in SIOCGIFCONF request. * Used to retrieve interface configuration * for machine (useful for programs which * must know all networks accessible). */ struct ifconf { int ifc_len; /* size of associated buffer */ union { caddr_t ifcu_buf; struct ifreq *ifcu_req; } ifc_ifcu; #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ }; SEE ALSO socket(), IoctlSocket() bsdsocket.library/-route- bsdsocket.library/-route- NAME route - kernel packet forwarding database SYNOPSIS #include #include #include int socket(PF_ROUTE, SOCK_RAW, int family); FUNCTION The kernel maintains a routing information database, which is used in selecting the appropriate network interface when transmitting packets. A user process (or possibly multiple co-operating processes) maintains this database by sending messages over a special kind of socket. This supplants fixed size IoctlSocket()'s used in earlier releases. Routing table changes may only be carried out by the super user. The operating system may spontaneously emit routing messages in response to external events, such as receipt of a re-direct, or failure to locate a suitable route for a request. The message types are described in greater detail below. Routing database entries come in two flavors: for a specific host, or for all hosts on a generic subnetwork (as specified by a bit mask and value under the mask. The effect of wildcard or default route may be achieved by using a mask of all zeros, and there may be hierarchical routes. When the system is booted and addresses are assigned to the network interfaces, each protocol family installs a routing table entry for each interface when it is ready for traffic. Normally the protocol specifies the route through each interface as a ``direct'' connection to the destination host or network. If the route is direct, the transport layer of a protocol family usually requests the packet be sent to the same host specified in the packet. Otherwise, the interface is requested to address the packet to the gateway listed in the routing entry (i.e. the packet is forwarded). When routing a packet, the kernel will attempt to find the most specific route matching the destination. (If there are two different mask and value-under-the-mask pairs that match, the more specific is the one with more bits in the mask. A route to a host is regarded as being supplied with a mask of as many ones as there are bits in the destination). If no entry is found, the destination is declared to be unreachable, and a routing-miss message is generated if there are any listers on the routing control socket described below. A wildcard routing entry is specified with a zero destination address value, and a mask of all zeroes. Wildcard routes will be used when the system fails to find other routes matching the destination. The combination of wildcard routes and routing redirects can provide an economical mechanism for routing traffic. One opens the channel for passing routing control messages by using the socket call shown in the synopsis above: The family parameter may be AF_UNSPEC which will provide routing information for all address families, or can be restricted to a specific address family by specifying which one is desired. There can be more than one routing socket open per system. Messages are formed by a header followed by a small number of sockadders, interpreted by position, and delimited by the new length entry in the sockaddr. The interpretation of which address are present is given by a bit mask within the header, and the sequence is least significant to most significant bit within the vector. Any messages sent to the kernel are returned, and copies are sent to all interested listeners. The kernel will provide the process id. for the sender, and the sender may use an additional sequence field to distinguish between outstanding messages. However, message replies may be lost when kernel buffers are exhausted. The kernel may reject certain messages, and will indicate this by filling in the rtm_errno field. The routing code returns EEXIST if requested to duplicate an existing entry, ESRCH if requested to delete a non-existent entry, or ENOBUFS if insufficient resources were available to install a new route. In the current implementation, all routing process run locally, and the values for rtm_errno are available through the normal errno mechanism, even if the routing reply message is lost. A process may avoid the expense of reading replies to its own messages by issuing a setsockopt() call indicating that the SO_USELOOPBACK option at the SOL_SOCKET level is to be turned off. A process may ignore all messages from the routing socket by doing a shutdown() system call for further input. If a route is in use when it is deleted, the routing entry will be marked down and removed from the routing table, but the resources associated with it will not be reclaimed until all references to it are released. User processes can obtain information about the routing entry to a specific destination by using a RTM_GET message. Messages include: #define RTM_ADD 0x1 /* Add Route */ #define RTM_DELETE 0x2 /* Delete Route */ #define RTM_CHANGE 0x3 /* Change Metrics, Flags, or Gateway */ #define RTM_GET 0x4 /* Report Information */ #define RTM_LOOSING 0x5 /* Kernel Suspects Partitioning */ #define RTM_REDIRECT 0x6 /* Told to use different route */ #define RTM_MISS 0x7 /* Lookup failed on this address */ #define RTM_RESOLVE 0xb /* request to resolve dst to LL addr */ A message header consists of: struct rt_msghdr { u_short rmt_msglen; /* to skip over non-understood messages */ u_char rtm_version; /* future binary compatibility */ u_char rtm_type; /* message type */ u_short rmt_index; /* index for associated ifp */ pid_t rmt_pid; /* identify sender */ int rtm_addrs; /* bitmask identifying sockaddrs in msg */ int rtm_seq; /* for sender to identify action */ int rtm_errno; /* why failed */ int rtm_flags; /* flags, incl kern & message, e.g. DONE */ int rtm_use; /* from rtentry */ u_long rtm_inits; /* which values we are initializing */ struct rt_metrics rtm_rmx; /* metrics themselves */ }; where: struct rt_metrics { u_long rmx_locks; /* Kernel must leave these values alone */ u_long rmx_mtu; /* MTU for this path */ u_long rmx_hopcount; /* max hops expected */ u_long rmx_expire; /* lifetime for route, e.g. redirect */ u_long rmx_recvpipe; /* inbound delay-bandwith product */ u_long rmx_sendpipe; /* outbound delay-bandwith product */ u_long rmx_ssthresh; /* outbound gateway buffer limit */ u_long rmx_rtt; /* estimated round trip time */ u_long rmx_rttvar; /* estimated rtt variance */ }; Flags include the values: #define RTF_UP 0x1 /* route usable */ #define RTF_GATEWAY 0x2 /* destination is a gateway */ #define RTF_HOST 0x4 /* host entry (net otherwise) */ #define RTF_REJECT 0x8 /* host or net unreachable */ #define RTF_DYNAMIC 0x10 /* created dynamically (by redirect) */ #define RTF_MODIFIED 0x20 /* modified dynamically (by redirect) */ #define RTF_DONE 0x40 /* message confirmed */ #define RTF_MASK 0x80 /* subnet mask present */ #define RTF_CLONING 0x100 /* generate new routes on use */ #define RTF_XRESOLVE 0x200 /* external daemon resolves name */ #define RTF_LLINFO 0x400 /* generated by ARP or ESIS */ #define RTF_STATIC 0x800 /* manually added */ #define RTF_BLACKHOLE 0x1000 /* just discard pkts (during updates) */ #define RTF_PROTO2 0x4000 /* protocol specific routing flag #1 */ #define RTF_PROTO1 0x8000 /* protocol specific routing flag #2 */ Specifiers for metric values in rmx_locks and rtm_inits are: #define RTV_SSTHRESH 0x1 /* init or lock _ssthresh */ #define RTV_RPIPE 0x2 /* init or lock _recvpipe */ #define RTV_SPIPE 0x4 /* init or lock _sendpipe */ #define RTV_HOPCOUNT 0x8 /* init or lock _hopcount */ #define RTV_RTT 0x10 /* init or lock _rtt */ #define RTV_RTTVAR 0x20 /* init or lock _rttvar */ #define RTV_MTU 0x40 /* init or lock _mtu */ Specifiers for which addresses are present in the messages are: #define RTA_DST 0x1 /* destination sockaddr present */ #define RTA_GATEWAY 0x2 /* gateway sockaddr present */ #define RTA_NETMASK 0x4 /* netmask sockaddr present */ #define RTA_GENMASK 0x8 /* cloning mask sockaddr present */ #define RTA_IFP 0x10 /* interface name sockaddr present */ #define RTA_IFA 0x20 /* interface addr sockaddr present */ #define RTA_AUTHOR 0x40 /* sockaddr for author of redirect */ NOTES Routing sockets were not part of the original AmiTCP specification. This is because the 4.3 BSD TCP/IP kernel, which AmiTCP is based upon, implemented this functionality differently. bsdsocket.library/-tcp- bsdsocket.library/-tcp- NAME tcp - Internet Transmission Control Protocol SYNOPSIS #include #include int socket(AF_INET, SOCK_STREAM, 0); FUNCTION The TCP protocol provides reliable, flow-controlled, two-way transmission of data. It is a byte-stream protocol used to support the SOCK_STREAM abstraction. TCP uses the standard Internet address format and, in addition, provides a per-host collection of ``port addresses''. Thus, each address is composed of an Internet address specifying the host and network, with a specific TCP port on the host identifying the peer entity. Sockets utilizing the tcp protocol are either ``active'' or ``passive''. Active sockets initiate connections to passive sockets. By default TCP sockets are created active; to create a passive socket the listen() system call must be used after binding the socket with the bind() system call. Only passive sockets may use the accept() call to accept incoming connections. Only active sockets may use the connect() call to initiate connections. Passive sockets may ``underspecify'' their location to match incoming connection requests from multiple networks. This technique, termed ``wildcard addressing'', allows a single server to provide service to clients on multiple networks. To create a socket which listens on all networks, the Internet address INADDR_ANY must be bound. The TCP port may still be specified at this time; if the port is not specified the system will assign one. Once a connection has been established the socket's address is fixed by the peer entity's location. The address assigned the socket is the address associated with the network interface through which packets are being transmitted and received. Normally this address corresponds to the peer entity's network. TCP supports one socket option which is set with setsockopt() and tested with getsockopt(). Under most circumstances, TCP sends data when it is presented; when outstanding data has not yet been acknowledged, it gathers small amounts of output to be sent in a single packet once an acknowledgement is received. For a small number of clients, such as window systems that send a stream of mouse events which receive no replies, this packetization may cause significant delays. Therefore, TCP provides a boolean option, TCP_NODELAY (from , to defeat this algorithm. The option level for the setsockopt call is the protocol number for TCP, available from getprotobyname(). Options at the IP transport level may be used with TCP; see ip. Incoming connection requests that are source-routed are noted, and the reverse source route is used in responding. ERRORS A socket operation may fail with one of the following errors returned: [EISCONN] When trying to establish a connection on a socket which already has one. [ENOBUFS] When the system runs out of memory for an internal data structure. [ETIMEDOUT] When a connection was dropped due to excessive retransmissions. [ECONNRESET] When the remote peer forces the connection to be closed. [ECONNREFUSED] When the remote peer actively refuses connection establishment (usually because no process is listening to the port). [EADDRINUSE] When an attempt is made to create a socket with a port which has already been allocated. [EADDRNOTAVAIL] When an attempt is made to create a socket with a network address for which no network interface exists. SEE ALSO getsockopt(), socket(), inet, ip bsdsocket.library/-udp- bsdsocket.library/-udp- NAME udp - Internet User Datagram Protocol SYNOPSIS #include #include int socket(AF_INET, SOCK_DGRAM, 0); FUNCTION UDP is a simple, unreliable datagram protocol which is used to support the SOCK_DGRAM abstraction for the Internet protocol family. UDP sockets are connectionless, and are normally used with the sendto and recvfrom calls, though the connect() call may also be used to fix the destination for future packets (in which case the recv() and send() system calls may be used). UDP address formats are identical to those used by TCP. In particular UDP provides a port identifier in addition to the normal Internet address format. Note that the UDP port space is separate from the TCP port space (i.e. a UDP port may not be ``connected'' to a TCP port). In addition broadcast packets may be sent (assuming the underlying network supports this) by using a reserved ``broadcast address''; this address is network interface dependent. Options at the IP transport level may be used with UDP; see ip. ERRORS A socket operation may fail with one of the following errors returned: [EISCONN] When trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected. [ENOTCONN] When trying to send a datagram, but no destination address is specified, and the socket hasn't been connected. [ENOBUFS] When the system runs out of memory for an internal data structure. [EADDRINUSE] When an attempt is made to create a socket with a port which has already been allocated. [EADDRNOTAVAIL] When an attempt is made to create a socket with a network address for which no network interface exists. SEE ALSO getsockopt(), recv(), send(), socket(), inet, ip bsdsocket.library/AbortInterfaceConfig bsdsocket.library/AbortInterfaceConfig NAME AbortInterfaceConfig - Attempt to abort an IP address allocation process currently in progress. SYNOPSIS AbortInterfaceConfig(message) A0 VOID AbortInterfaceConfig(struct AddressAllocationMessage * message); FUNCTION The interface address allocation process is asynchronous by nature; it may take its time to complete, but you may not want to wait for this to happen. You can try to abort the process with this routine. INPUTS message -- Pointer to a 'struct AddressAllocationMessage' message which has been sent using the BeginInterfaceConfig() routine. NOTES The AbortInterfaceConfig() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. There is no guarantee that the message can be intercepted and the IP address allocation process aborted by this routine. In fact, the process can complete before this routine has managed to abort it. SEE ALSO BeginInterfaceConfig() bsdsocket.library/accept bsdsocket.library/accept NAME accept - accept a connection on a socket SYNOPSIS #include #include socket = accept(s, addr, addrlen) D0 D0 A0 A1 long accept(long s, struct sockaddr *addr, long *addrlen); FUNCTION The argument s is a socket that has been created with socket(), bound to an address with bind(), and is listening for connections after a listen(). The accept() argument extracts the first connection request on the queue of pending connections, creates a new socket with the same properties of s and allocates a new file descriptor for the socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept() returns an error as described below. The accepted socket may not be used to accept more connections. The original socket s remains open. The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the domain in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently with SOCK_STREAM. It is possible to WaitSelect() a socket for the purposes of doing an accept() by selecting it for read. One can obtain user connection request data without confirming the connection by issuing a recvmsg() call with an msg_iovlen of 0 and a non-zero msg_controllen, or by issuing a getsockopt() request. Similarly, one can provide user connection rejection information by issuing a sendmsg() call with providing only the control information, or by calling setsockopt(). RESULT The call returns -1 on error. If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. ERRORS The accept() will fail if: [EBADF] The descriptor is invalid. [ENOTSOCK] The descriptor references a file, not a socket. [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. [EFAULT] The addr parameter is not in a writable part of the user address space. [EWOULDBLOCK] The socket is marked non-blocking and no connections are present to be accepted. SEE ALSO bind(), connect(), listen(), WaitSelect(), socket() bsdsocket.library/AddDomainNameServer bsdsocket.library/AddDomainNameServer NAME AddDomainNameServer - Add another domain name server address to the local resolver database. SYNOPSIS success = AddDomainNameServer(address) D0 A0 LONG AddDomainNameServer(STRPTR address); FUNCTION AddDomainNameServer() adds another address to the local resolver database. This does not modify the on-disk resolver database, the change only affects the in-memory copy. INPUTS address -- Domain name server address as a pointer to a NUL-terminated string; the address must be given in dotted-decimal notation (per RFC1700). RESULT If the address could be added, a 0 value is returned. A return value of -1 indicates an error, which is further specified in the global errno. ERRORS The AddDomainNameServer() call will fail if: [ENOBUFS] There was not enough memory left to add a new database entry. [EINVAL] The IP address is not valid. [EFAULT] The address parameter is not valid. NOTES The AddDomainNameServer() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_DNS_API tag with the SocketBaseTagList() function. This call nests, i.e. adding the same address twice will require two calls RemoveDomainNameServer() to remove it again. The local in-memory domain name server database is scanned before the on-disk configuration file is examined. SEE ALSO RemoveDomainNameServer(), SocketBaseTagList() bsdsocket.library/AddInterfaceTagList bsdsocket.library/AddInterfaceTagList NAME AddInterfaceTagList - Make a new interface available for network access SYNOPSIS success = AddInterfaceTagList(name,device,unit,tags) D0 A0 A1 D0 A2 long AddInterfaceTagList(STRPTR name,STRPTR device,LONG unit, struct TagItem *tags); long AddInterfaceTags(STRPTR name,STRPTR device, LONG unit,...); FUNCTION This function makes another device available for network access. Each such device must be assigned a unique interface name and refer to a SANA-II device name and unit number. INPUTS name -- Unique name of the interface, as will be later referred to with the stack's API (e.g. IoctlSocket()). This name cannot be longer than 15 characters. device -- Name of the SANA-II device driver to associate with the interface. unit -- The device driver unit to use. tags -- Pointer to a 'struct TagItem' list. TAGS IFA_IPType (LONG) - Overrides the packet type the stack uses when sending IP packets. Default is 2048. IFA_ARPType (LONG) - Overrides the packet type the stack uses when sending ARP packets. Default is 2054. IFA_NumReadRequests (LONG) - Overrides the number of IP read requests to allocate and queue for the underlying SANA-II device driver to use. Default is 32. IFA_NumWriteRequests (LONG) - Overrides the number of IP write requests to allocate and queue for the underlying SANA-II device driver to use. Default is 32. IFA_NumARPRequests (LONG) - Overrides the number of ARP requests to allocate and queue for the underlying SANA-II device driver to use. Default is 4. . IFA_PacketFilterMode (LONG) - Configure the packet filter mode access permitted for this interface. Possible options are: PFM_Nothing The filter is disabled for this interface. PFM_Local Enables filtering on all IP and ARP packets that are intended for this particular interface. Packets intended for other interfaces or hosts are ignored. PFM_IPandARP Enables filtering on all IP and ARP packets that happen to fly by this interface, no matter whether the packets are intended for it or not. This requires that the underlying network device driver is opened for exclusive access in so-called 'promiscuous' mode. This may not work if other clients (Envoy, ACS) need to keep the driver opened. PFM_Everything Enables filtering on all packet types that happen to pass by, regardless of their type and contents. This requires that the underlying network device driver is opened for exclusive access in so-called 'promiscuous' mode. This may not work if other clients (Envoy, ACS) need to keep the driver opened. Please note that packets which are not of the IP and ARP types will not be processed by the TCP/IP stack. Thus, your filter may see the packets but they will eventually be quietly discarded. Default is PFM_Local. Note that this option only configures the limits and possibilities open to the Berkeley Packet Filter mechanism, but does not enable the filter. IFA_PointToPoint (BOOL) - Choose whether this interface is of the point-to-point type. Not normally necessary since the stack can figure this out all by itself. IFA_Multicast (BOOL) - This option tells the stack that this device can handle multicast packets. It is enabled by default for Ethernet hardware, and is assumed to be FALSE for all other hardware types. Default for this option is TRUE for Ethernet hardware and FALSE for every other kind of hardware. IFA_DownGoesOffline (BOOL) - This option is useful with point-to-point devices, like 'ppp.device'. When specified, bringing the interface 'down' or shutting down the stack will cause the associated SANA-II device driver to be switched offline (via the 'S2_OFFLINE' command). Default is FALSE. IFA_ReportOffline (BOOL) - When a device is switched offline, you may want to know about it. This is helpful with SLIP/PPP connections which run over a serial link which accumulates costs while it is open. When the connection is broken and the device goes offline, you will receive a brief notification of what happened. However, if you tell the library itself to shut down, no notification that a device was switched offline will be shown. Default is FALSE. IFA_RequiresInitDelay (BOOL) - Some devices need a little time to settle after they have been opened or they will hickup and lose data after the first packet has been sent. For these devices, this option will cause a delay of about a second before the first packet is sent. Default is TRUE. IFA_CopyMode (LONG) - This enables special data copying code which may not be compatible with all SANA-II devices. This can be one of the following options: CM_SlowWordCopy Use the default data copying code. Not necessarily the fastest way to transfer the data, but should work with all drivers. CM_FastWordCopy Use the faster data copying code. This may not work reliably with all devices. Default is CM_SlowWordCopy. IFA_HardwareAddress (struct InterfaceHardwareAddress *) - You can try to configure the interface's hardware address when it is added. Note that this typically works only once for every driver. The address to be used must be stored in the following data structure: struct InterfaceHardwareAddress { LONG iha_Length; UBYTE * iha_Address; }; The structure members have the following purposes: iha_Length Address length, given in number of bits. For example, an Ethernet MAC address would be 48 bits in size. iha_Address Points to the first byte that contains the address. For example, there are six bytes in an Ethernet MAC address. Addresses that are too long for the underlying hardware to fit will be truncated. IFA_SetDebugMode (BOOL) - Enable or disable debugging mode for this interface. This option defaults to FALSE. IFA_LimitMTU (ULONG) - You can limit the size of the maximum transmission unit (MTU) configured for this interface. Normally, this value is predefined by the hardware driver, but you can request that a smaller size is used. This can help if, in order to route packets properly, an artificial limit is imposed on the maximum packet size. By default the MTU value provided by the hardware driver is used. RESULT success -- 0 for success, -1 for failure; the failure code will be stored in the 'errno' variable. NOTES The AddInterfaceTagList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. This function is intended to be a simplified, specialized front end to the underlying interface socket API. If you want more than this function can do for you, use the interface socket API. SEE ALSO ConfigureInterfaceTagList(), QueryInterfaceTagList() bsdsocket.library/AddNetMonitorHookTagListet.library/AddNetMonitorHookTagList NAME AddNetMonitorHookTagList - Add a network monitoring callback hook. SYNOPSIS success = AddNetMonitorHookTagList(type,hook,tags) D0 D0 A0 A1 long AddNetMonitorHookTagList(long type,struct Hook *hook, struct TagItem *tags) long AddNetMonitorHookTags(long type,struct Hook *hook,...); FUNCTION This function is for adding network monitoring callback hooks. There are different types of hooks to be installed, each for one particular purpose. Monitoring hooks can be used both for inspecting and filtering data that enters the stack, or for denying access to certain APIs. More than one hook can be installed for each monitoring task. INPUTS type -- The type of monitoring hook to install; this must be one of the following: MHT_ICMP Monitor incoming ICMP messages. MHT_UDP Monitor incoming UDP datagrams. MHT_TCP_Connect Monitor incoming TCP segments that are about to initiate a connection. MHT_Connect Monitor calls to the connect() function. MHT_Send Monitor calls to the send(), sendto() and sendmsg() calls. MHT_Packet Monitor incoming and outgoing packets. MHT_Bind Monitor calls to the bind() function. hook -- Pointer to a Hook to be invoked for monitoring; the Hook will be added to an interal list and must be removed before the library is closed. Depending on the type of monitoring task, the hook will be invoked with different parameters: MHT_ICMP action = hookfunc(hook,reserved,imm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct ICMPMonitorMessage *imm); The hook function will be invoked from withing the TCP/IP stack itself, which disallows calls into "bsdsocket.library". Since the hook code may be invoked frequently, your code should perform its tasks swiftly and without delay. The 'reserved' parameter will be set to NULL for future expansion. The contents of the 'ICMPMonitorMessage' must not be modified as they will be forwarded to the next hook in line, which will want to take another look at it. The 'action' value the hook function returns decides the fate of the ICMP message. The following actions are supported: MA_Continue The ICMP message will be processed as usual. MA_Ignore The ICMP message will be ignored, but will end up in the raw IP processing framework. MA_Drop The ICMP message will be ignored and dropped as if it had a checksum error. MHT_UDP action = hookfunc(hook,reserved,umm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct UDPMonitorMessage *umm); The hook function will be invoked from withing the TCP/IP stack itself, which disallows calls into "bsdsocket.library". Since the hook code may be invoked frequently, your code should perform its tasks swiftly and without delay. The 'reserved' parameter will be set to NULL for future expansion. The contents of the 'UDPMonitorMessage' must not be modified as they will be forwarded to the next hook in line, which will want to take another look at it. The 'action' value the hook function returns decides the fate of the UDP datagram. The following actions are supported: MA_Continue The UDP datagram will be processed as usual. MA_Drop The UDP datagram will be ignored and dropped as if it had a checksum error. MHT_TCP_Connect action = hookfunc(hook,reserved,tcmm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct TCPConnectMonitorMessage *tcmm); The hook function will be invoked from withing the TCP/IP stack itself, which disallows calls into "bsdsocket.library". Since the hook code may be invoked frequently, your code should perform its tasks swiftly and without delay. The 'reserved' parameter will be set to NULL for future expansion. The contents of the 'TCPConnectMonitorMessage' must not be modified as they will be forwarded to the next hook in line, which will want to take another look at it. The hook will be invoked before the regular TCP segment processing begins, which attempts to establish a connection. Specifically, the hook code is invoked before the TCP three way handshake procedure has even started, or the stack has determined whether there is a socket ready to accept the incoming connection request. The 'action' value the hook function returns decides the fate of the TCP segment. The following actions are supported: MA_Continue The TCP segment will be processed as usual. MA_Drop The TCP segment will be ignored and dropped as if it had a checksum error. The remote will not receive any notification of the segment having been dropped and may have to time out and retransmit it. MA_DropWithReset The TCP segment will be ignored and dropped as if it had a checksum error. In return the remote will receive a notification in the form of a connection reset, which will allow it to recover immediately. If you want to reject a connection request, this is the most graceful way to do it. MHT_Connect error = hookfunc(hook,reserved,cmm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct ConnectMonitorMsg *cmm); The hook function will be invoked before dropping into the kernel 'connect()' call. This allows you to perform any necessary "bsdsocket.library" calls before you decide whether the call should proceed or be terminated with an error. The 'reserved' parameter will be set to NULL for future expansion. The contents of the 'ConnectMonitorMessage' must not be modified as they will be forwarded to the next hook in line, which will want to take another look at it. The 'error' value the hook function returns decides whether the call can proceed as usual or not. An error value of 0 will allow the call to proceed (unless another hook denies this), and any error value > 0 will cause the call to be aborted and the errno variable to be set to this value. MHT_Bind error = hookfunc(hook,reserved,cmm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct BindMonitorMsg *cmm); The hook function will be invoked before dropping into the kernel 'bind()' call. This allows you to perform any necessary "bsdsocket.library" calls before you decide whether the call should proceed or be terminated with an error. The 'reserved' parameter will be set to NULL for future expansion. The contents of the 'BindMonitorMessage' must not be modified as they will be forwarded to the next hook in line, which will want to take another look at it. The 'error' value the hook function returns decides whether the call can proceed as usual or not. An error value of 0 will allow the call to proceed (unless another hook denies this), and any error value > 0 will cause the call to be aborted and the errno variable to be set to this value. MHT_Send error = hookfunc(hook,reserved,smm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct SendMonitorMsg *smm); The hook function will be invoked before dropping into the kernel 'send()', 'sendto()' or 'sendmsg()' calls. This allows you to perform any necessary "bsdsocket.library" calls before you decide whether the call should proceed or be terminated with an error. The 'reserved' parameter will be set to NULL for future expansion. The contents of the 'SendMonitorMessage' must not be modified as they will be forwarded to the next hook in line, which will want to take another look at it. The 'error' value the hook function returns decides whether the call can proceed as usual or not. An error value of 0 will allow the call to proceed (unless another hook denies this), and any error value > 0 will cause the call to be aborted and the errno variable to be set to this value. Depending upon the type of function to perform, the contents of the SendMonitorMessage may look different. For example, either the 'smm_To' or the 'smm_Msg' field will be NULL. MHT_Packet action = hookfunc(hook,reserved,pmm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct PacketMonitorMessage *pmm); The hook function will be invoked from withing the TCP/IP stack itself, which disallows calls into "bsdsocket.library". Since the hook code may be invoked frequently, your code should perform its tasks swiftly and without delay. The 'reserved' parameter will be set to NULL for future expansion. The contents of the 'PacketMonitorMessage' must not be modified as they will be forwarded to the next hook in line, which will want to take another look at it. The 'action' value the hook function returns decides the fate of the packet. The following actions are supported: MA_Continue The packet will be processed as usual. MA_Drop The packet will be ignored and dropped as if it had a checksum error. tags -- Pointer to a 'struct TagItem' list. No tags are defined yet. RESULT If the action is successful, a 0 value is returned. A return value of -1 indicates an error, which is further specified in the global errno. ERRORS The AddNetMonitorHookTagList() call fails if: [EFAULT] The hook parameter is not valid. [EINVAL] The monitor type is not supported. NOTES The AddNetMonitorHookTagList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_MONITORING_API tag with the SocketBaseTagList() function. SEE ALSO RemoveNetMonitorHook() bsdsocket.library/AddRouteTagList bsdsocket.library/AddRouteTagList NAME AddRouteTagList - Add entries to the networking routing tables SYNOPSIS success = AddRouteTagList(tags) D0 A0 long AddRouteTagList(struct TagItem *tags); long AddRouteTags(Tag tag1,...); FUNCTION This function is for manipulating the networking routing tables by adding new entries to them. Typical applications involve adding a route to a point to point partner or selecting the default route any packet not intended for the local host should take. INPUTS tags -- Pointer to a 'struct TagItem' list. TAGS RTA_Destination (STRPTR) -- The route's destination address, which must be specified as a NUL-terminated string. The string can contain a host name to be resolved or an IP address in dotted-decimal notation (see RFC1700). The RTA_Destination tag can be used in conjunction with the RTA_Gateway tag. RTA_Gateway (STRPTR) -- The address of the gateway that forwards packets to the destination address. This must be a NUL- terminated string referring to a host name to be resolved or an IP address in dotted-decimal notation (see RFC1700). The RTA_Gateway tag requires the use of the RTA_Destination tag. RTA_DefaultGateway (STRPTR) -- The address of the default gateway all packets will be forwarded to which cannot be sent along any other known route. This must be a NUL-terminated string referring to a host name to be resolved or an IP address in dotted-decimal notation. The RTA_DefaultGateway tag excludes the use of the RTA_Destination and RTA_Gateway tags. RTA_DestinationHost (STRPTR) - Like RTA_Destination, but forces the destination address to be interpreted as a host. Otherwise, if the destination has a local address part of INADDR_ANY or if the destination is the symbolic name of a network, then the route is assumed to be a to a network. RTA_DestinationNet (STRPTR) - Like RTA_Destination, but forces the destination address to be interpreted as a network. RESULT success -- 0 for success, -1 for failure; the failure code will be stored in the 'errno' variable. NOTES The AddRouteTagList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ROUTING_API tag with the SocketBaseTagList() function. This function is intended to be a simplified, specialized front end to the underlying routing socket API. If you want more than this function can do for you, use the routing socket API. Take care, as this functionality is not present in the original AmiTCP implementation. SEE ALSO DeleteRouteTagList(), route bsdsocket.library/BeginInterfaceConfig bsdsocket.library/BeginInterfaceConfig NAME BeginInterfaceConfig - Attempt to allocate an IP address for an interface. SYNOPSIS BeginInterfaceConfig(message) A0 VOID BeginInterfaceConfig(struct AddressAllocationMessage * message); FUNCTION This routine uses the Bootstrap Protocol (BOOTP; see RFC951), the Dynamic Host Configuration Protocol (DHCP; RFC 2131) or a different dynamic address configuration protocol to obtain configuration information for a specific network interface. A BOOTP request will be set up, sent and resent in regular intervals until either a timeout occurs or a BOOTP/DHCP server responds. Since this process is asynchronous by nature, it is started by sending a message whose contents the caller has to fill in and in which the BOOTP message result will be returned. INPUTS message -- Pointer to a 'struct AddressAllocationMessage' message which must be properly initialized (see below). When the message has been processed, it will be returned to the caller via 'ReplyMsg()'. MESSAGE The message must be initialized like any other kind of 'struct Message' that is to be attached to a MsgPort and eventually replied with 'ReplyMsg()'. Unless described otherwise, all members of the message must be set to zero before it is handed over to BeginInterfaceConfig(). The individual structure members should be initialized as follows: aam_Version The version of the message, corresponding to a particular layout and contents. The message format may change in future releases. The version described in this documentation is #1. You must fill in this member or the message will be rejected. aam_Protocol This must be one of AAMP_BOOTP, AAMP_DHCP, AAMP_SLOWAUTO or AAMP_FASTAUTO. AAMP_BOOTP stands for the Bootstrap Protocol (RFC 951). AAMP_DHCP stands for the Dynamic Host Configuration Protocol (RFC 2131). AAMP_SLOWAUTO stands for an automatic IPv4 address configuration protocol with conflict detection which is currently being standardized. AAMP_FASTAUTO stands for the same protocol, which runs through the individual steps of the protocol much faster than AAMP_SLOWAUTO. Only the DHCP protocol honours your choice of IP address and net mask. The others will ignore this information. The AAMP_SLOWAUTO/AAMP_FASTAUTO protocol only configures the IP address and nothing else. The same is true for the BOOTP protocol. The AAMP_SLOWAUTO/AAMP_FASTAUTO protocol will pick an IP address from the 169.254/16 range, with the two last octets of the address filled in with random data. The address will be tested to avoid collisions. Eventually, the configuration process will settle on a choice that works. If somewhere down the line an address collision is detected, the address picked will be defended. But if further collisions are found, a new address will be picked. This can disrupt TCP/IP traffic for the local host but it should be very rare to happen. To keep the likelyhood of collisions low, do not use this protocol in an environment in which more than 1,300 are using the same protocol. The same protocol is used by 'MacOS 9' and beyond and by the Microsoft Windows operating system family starting with 'Windows 98'. The main difference between the AAMP_SLOWAUTO and AAMP_FASTAUTO protocol flavours is that they use timeouts of different length. The AAMP_SLOWAUTO protocol is intended to be used in Ethernet networks with switches which use the IEEE Spanning Tree Protocol (802.1d). The route configuration in such networks can take a while, which is why the AAMP_SLOWAUTO timeouts have to be on the order of several seconds. AAMP_FASTAUTO protocol is intended to be used for wireless networks which react faster to route changes; the timeouts are therefore on the order of several milliseconds which is far more responsive than the AAMP_SLOWAUTO protocol. aam_InterfaceName The name of the interface to allocate an IP address for. aam_Timeout Number of seconds to wait for a BOOTP/DHCP server to respond. Due to how the configuration process works, the timeout must be at least 10 seconds long. If it is shorter, it is automatically extended to 10 seconds. aam_LeaseTime This option is relevant only for DHCP. It allows you to specify the interface address lease time to request from the server. The default is DHCP_DEFAULT_LEASE_TIME, which accepts the server's choice. The value DHCP_INFINITE_LEASE_TIME will attempt to bind the interface address permanently. All other values refer to the number of seconds the lease should be allocated. Note that the server may choose to ignore your preferred lease time. aam_RequestedAddress A DHCP client can make a wish, as to which IP address should be allocated for it. This is where you provide your choice. Leave 'aam_RequestedAddress' zero to accept the default. Note that the server may ignore your wish. Make sure that your application does not assume that it is always allocated the IP address you requested. The allocation process will eventually reset 'aam_RequestedAddress' to zero. aam_ClientIdentifier Allocating an IP address for a DHCP client is not that helpful if the client cannot be referred to by its name after an address has been assigned to it. You can request a name to be bound to the IP address to assign using the 'aam_ClientIdentifier' member: it must point to a NUL-terminated string which can be up to 255 characters in size. Names longer than 255 characters will be truncated, names shorter than 2 characters will be ignored. The name string should contain only 7-bit ASCII characters and preferably, should be short, too. Not all DHCP servers can store client names of arbitrary length. If you do not want a name to be assigned, set 'aam_ClientIdentifier' to NULL. aam_NAKMessage aam_NAKMessageSize The server may refuse to allocate an IP address for this interface and provide an explanation. To obtain the explanatory text, put a pointer to a string into 'aam_NAKMessage' and the size of that string into 'aam_NAKMessageSize'. If a response text is received, it will be copied to the string. aam_RouterTable aam_RouterTableSize The server may provide a list of routers the protocol stack should use when forwarding packets. To find out which routers were provided, put the address of a table of 32 bit integers (unsigned long) into 'aam_RouterTable' and the number of entries in that table into 'aam_RouterTableSize'. If a list of routers is received, their addresses will be copied into the table. A router address of 0 should be ignored. aam_DNSTable aam_DNSTableSize The server may provide a list of domain name servers the resolver should use. To find out which name servers were provided, put the address of a table of 32 bit integers (unsigned long) into 'aam_DNSTable' and the number of entries in that table into 'aam_DNSTableSize'. If a list of domain servers is received, their addresses will be copied into the table. A server address of 0 should be ignored. aam_StaticRouteTable aam_StaticRouteTableSize The server may provide a list of static routes the protocol stack should use. To find out which static routes were provided, put the address of a table of 32 bit integers (unsigned long) into 'aam_StaticRouteTable' and the number of entries in that table into 'aam_StaticRouteTableSize'. If a list of static routes is received, their addresses will be copied into the table. A route address of 0 should be ignored. aam_HostName aam_HostNameSize The server may provide the name to be used by the local host. To find out which name was assigned, put the address of a string into 'aam_HostName' and the size of that string into 'aam_HostNameSize'. If a host name is received, you will receive a NUL-terminated string. aam_DomainName aam_DomainNameSize The server may provide the name of the domain the local host is in. To find out which name was assigned, put the address of a string into 'aam_DomainName' and the size of that string into 'aam_DomainNameSize'. If a domain name is received, you will receive a NUL-terminated string. aam_BOOTPMessage aam_BOOTPMessageSize You can receive a copy of the BOOTP response message that was received by the protocol stack. Put the address of your local message buffer into 'aam_BOOTPMessage' and the size of that buffer (in bytes) into 'aam_BOOTPMessageSize'. If the BOOTP request is answered, you will find a copy of the BOOTP response message in the buffer. aam_LeaseExpires When the interface is first configured using DHCP the lease expiration time can be copied to a user supplied DateStamp. If the lease is infinitely long, then the DateStamp will contain all zeroes. When the message is eventually replied, the following structure members will have been filled in: aam_Result This can be one of the following values: AAMR_Success An IP address was successfully allocated. AAMR_Aborted The allocation request was aborted. AAMR_Timeout The allocation has failed since it could not be completed in the requested time span. AAMR_InterfaceNotKnown The name of the network interface you provided is not known. AAMR_InterfaceWrongType The BOOTP protocol only works with broadcast interfaces (e.g. Ethernet hardware). The interface you provided is not of this kind. AAMR_AddressKnown The interface already has an IP address assigned. AAMR_VersionUnknown The data structure version you provided is not supported. AAMR_NoMemory There was not enough memory available to process your request. AAMR_AddrChangeFailed The interface address could not be changed. AAMR_MaskChangeFailed The interface network mask could not be changed. AAMR_Ignored Your request was not understood and was therefore ignored. AAMR_Busy Address allocation is already in progress for this interface. aam_Address The IP address assigned to this interface. aam_ServerAddress The IP address of the BOOTP server which responsed to the query; this may be 0. aam_SubnetMask The interface's subnet mask; this may be 0. aam_NAKMessage Filled in with an error message; may be empty. aam_RouterTable Filled in with the addresses of the routers to use. The addresses are listed in descending order of preference. This list may be empty and contain invalid IP addresses (e.g. 0.0.0.0). aam_DNSTable Filled in with the addresses of the domain name servers use. The addresses are listed in descending order of preference. This list may be empty and contain invalid IP addresses (e.g. 0.0.0.0). aam_StaticRouteTable Filled in with the destination addresses of static routes. The addresses are listed in descending order of preference. This list may be empty and contain invalid IP addresses (e.g. 0.0.0.0). aam_HostName The name assigned to this host; this may be empty. aam_DomainName The domain name assigned to this host; this may be empty. aam_BOOTPMessage A copy of the BOOTP response; this may be empty if 'aam_Result != AAMR_Success'. NOTES The BeginInterfaceConfig() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. This routine starts an asynchronous operation, very much like exec.library/SendIO(). It may take its time to complete. To abort it before it has completed, use the AbortInterfaceConfig() routine. DHCP is built on top of BOOTP, which is why the documentation uses both terms interchangeably. Note, however, that the actual protocols work very differently and support different features. BOOTP only reports an IP address for you to use permanently whereas DHCP will cause the interface address to be updated and renewed repeatedly over time. SEE ALSO AbortInterfaceConfig() bsdsocket.library/bind bsdsocket.library/bind NAME bind - bind a name to a socket SYNOPSIS #include #include success = bind(s, name, namelen) D0 D0 A0 D1 long bind(long s, struct sockaddr *name, long namelen); FUNCTION bind() assigns a name to an unnamed socket. When a socket is created with socket() it exists in a name space (address family) but has no name assigned. bind() requests that name be assigned to the socket. RESULT If the bind is successful, a 0 value is returned. A return value of -1 indicates an error, which is further specified in the global errno. ERRORS The bind() call will fail if: [EBADF] S is not a valid descriptor. [ENOTSOCK] S is not a socket. [EADDRNOTAVAIL] The specified address is not available from the local machine. [EADDRINUSE] The specified address is already in use. [EINVAL] The socket is already bound to an address. [EACCES] The requested address is protected, and the current user has inadequate permission to access it. [EFAULT] The name parameter is not in a valid part of the user address space. SEE ALSO connect(), listen(), socket(), getsockname() bsdsocket.library/bpf_close bsdsocket.library/bpf_close NAME bpf_close - close a packet filter channel SYNOPSIS success = bpf_close(handle) D0 D0 long bpf_close(long handle); FUNCTION The bpf_close() call will close a packet filter channel previously allocated with bpf_open(). INPUTS handle -- Handle number returned by previous call to bpf_open(). RESULT A 0 is returned if the call succeeds, -1 if it fails. NOTES The bpf_close() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. ERRORS The call succeeds unless: [ENXIO] The channel handle does not refer to a valid packet filter channel. [EPERM] You are not the owner of this channel. SEE ALSO bpf_open(), bpf_read(), bpf_write(), bpf_set_notify_mask(), bpf_set_interrupt_mask(), bpf_ioctl(), bpf_data_waiting() bsdsocket.library/bpf_data_waiting bsdsocket.library/bpf_data_waiting NAME bpf_data_waiting - query whether there is data waiting to be read with bpf_read() SYNOPSIS waiting = bpf_data_waiting(handle) D0 D0 long bpf_data_waiting(long handle); FUNCTION The bpf_data_waiting() call allows you to query whether there is currently data waiting to be read via bpf_read(). INPUTS handle -- Handle number returned by previous call to bpf_open(). RESULT A return value of 0 indicates that there is no data waiting to be read, a 1 that there is data waiting. A value of -1 indicates an error. NOTES The bpf_data_waiting() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. ERRORS The call succeeds unless: [ENXIO] The channel handle does not refer to a valid packet filter channel. [EPERM] You are not the owner of this channel. SEE ALSO bpf_open(), bpf_close(), bpf_read(), bpf_write(), bpf_set_notify_mask(), bpf_set_interrupt_mask(), bpf_ioctl() bsdsocket.library/bpf_ioctl bsdsocket.library/bpf_ioctl NAME bpf_ioctl - control packet filter parameters SYNOPSIS #include #include #include #include #include success = bpf_ioctl(handle, request, argp) D0 D0 D1 A0 long bpf_ioctl(long handle, unsigned long request, char *argp); FUNCTION The bpf_ioctl() function manipulates the underlying device parameters of the packet filter. An ioctl request has encoded in it whether the argument is an ``in'' parameter or ``out'' parameter, and the size of the argument argp in bytes. Macros and defines used in specifying an ioctl request are located in the file . The following request types are supported: FIONREAD The argument must be (long *). The variable pointed to will be set to 0 if there is no data waiting to be read, otherwise it will contain the number of bytes waiting. SIOCGIFADDR The argument must be (struct sockaddr_in *). It will be filled with the address of the interface associated with this channel. BIOCGBLEN The argument must be (long *). The size of the buffer, as to be passed to bpf_read(), will be returned. BIOCSBLEN The argument must be (long *). Sets the buffer length for reads on bpf files. The buffer must be set before the file is attached to an interface with BIOCSETIF. If the requested buffer size cannot be accomodated, the closest allowable size will be set and returned in the argument. A read call will result in EIO if it is passed a buffer that is not this size. BIOCSETF The argument must be (struct bpf_program *). Sets the filter program used by the kernel to discard uninteresting packets. An array of instructions and its length is passed in using the following structure: struct bpf_program { int bf_len; struct bpf_insn *bf_insns; }; The filter program is pointed to by the bf_insns field while its length in units of `struct bpf_insn' is given by the bf_len field. Also, the actions of BIOCFLUSH are performed. See the section FILTER MACHINE for an explanation of the filter language. BIOCFLUSH Flushes the buffer of incoming packets, and resets the statistics that are returned by BIOCGSTATS. BIOCGDLT The argument must be (long *). The link layer type is returned, which can be either DLT_EN10MB, DLT_NULL or DLT_SLIP. DLT_EN10MB stands for Ethernet link layer encapsulation, DLT_SLIP and DLT_NULL stand for no link layer encapsulation. BIOCGETIF The argument must be (struct ifreq *). Returns the name of the hardware interface that the file is listening on. The name is returned in the if_name field of ifr. All other fields are undefined. BIOCSETIF The argument must be (struct ifreq *). Sets the hardware interface associate with the file. This command must be performed before any packets can be read. The device is indicated by name using the if_name field of the ifreq. Additionally, performs the actions of BIOCFLUSH. BIOCSRTIMEOUT The argument must be (struct timeval *). Set the timeout for the bpf_read() command. BIOCGRTIMEOUT The argument must be (struct timeval *). Returns the timeout used by the bpf_read() command. BIOCGSTATS The argument must be (struct bpf_stat *). Returns the following structure of packet statistics: struct bpf_stat { u_int bs_recv; u_int bs_drop; }; The fields are: bs_recv The number of packets received by the descriptor since opened or reset (including any buffered since the last read call). bs_drop The number of packets which were accepted by the filter but dropped by the kernel because of buffer overflows (i.e., the application's reads aren't keeping up with the packet traffic). BIOCIMMEDIATE The argument must be (long *). Enable or disable ``immediate mode'', based on the truth value of the argument. When immediate mode is enabled, reads return immediately upon packet reception. Otherwise, a read will block until either the kernel buffer becomes full or a timeout occurs. This is useful for programs like rarpd, which must respond to messages in real time. The default for a new file is off. BIOCVERSION The argument must be (struct bpf_version *). Returns the major and minor version numbers of the filter languange currently recognized by the kernel. Before installing a filter, applications must check that the current version is compatible with the running kernel. Version numbers are compatible if the major numbers match and the application minor is less than or equal to the kernel minor. The kernel version number is returned in the following structure: struct bpf_version { u_short bv_major; u_short bv_minor; }; The current version numbers are given by BPF_MAJOR_VERSION and BPF_MINOR_VERSION from . An incompatible filter may result in undefined behavior (most likely, an error returned by bpf_ioctl() or haphazard packet matching). RESULT A 0 is returned if the call succeeds, -1 if it fails. NOTES The bpf_ioctl() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. ERRORS bpf_ioctl() will fail if: [ENXIO] The channel handle does not refer to a valid packet filter channel. [EPERM] You are not the owner of this channel. [EINVAL] Request or argp is not valid, the filter is not attached to an interface, or the buffer size is too large. FILTER MACHINE A filter program is an array of instructions, with all branches forwardly directed, terminated by a return instruction. Each instruction performs some action on the pseudo-machine state, which consists of an accumulator, index register, scratch memory store, and implicit program counter. The following structure defines the instruction format: struct bpf_insn { u_short code; u_char jt; u_char jf; long k; }; The k field is used in differnet ways by different insutructions, and the jt and jf fields are used as offsets by the branch intructions. The opcodes are encoded in a semi-hierarchical fashion. There are eight classes of intructions: BPF_LD, BPF_LDX, BPF_ST, BPF_STX, BPF_ALU, BPF_JMP, BPF_RET, and BPF_MISC. Various other mode and operator bits are or'd into the class to give the actual instructions. The classes and modes are defined in . Below are the semantics for each defined BPF instruction. We use the convention that A is the accumulator, X is the index register, P[] packet data, and M[] scratch memory store. P[i:n] gives the data at byte offset ``i'' in the packet, interpreted as a word (n=4), unsigned halfword (n=2), or unsigned byte (n=1). M[i] gives the i'th word in the scratch memory store, which is only addressed in word units. The memory store is indexed from 0 to BPF_MEMWORDS-1. k, jt, and jf are the corresponding fields in the instruction definition. ``len'' refers to the length of the packet. BPF_LD These instructions copy a value into the accumulator. The type of the source operand is specified by an ``addressing mode'' and can be a constant (BPF_IMM), packet data at a fixed offset (BPF_ABS), packet data at a variable offset (BPF_IND), the packet length (BPF_LEN), or a word in the scratch memory store (BPF_MEM). For BPF_IND and BPF_ABS, the data size must be specified as a word (BPF_W), halfword (BPF_H), or byte (BPF_B). The semantics of all the recognized BPF_LD instructions follow. BPF_LD+BPF_W+BPF_ABS A <- P[k:4] BPF_LD+BPF_H+BPF_ABS A <- P[k:2] BPF_LD+BPF_B+BPF_ABS A <- P[k:1] BPF_LD+BPF_W+BPF_IND A <- P[X+k:4] BPF_LD+BPF_H+BPF_IND A <- P[X+k:2] BPF_LD+BPF_B+BPF_IND A <- P[X+k:1] BPF_LD+BPF_W+BPF_LEN A <- len BPF_LD+BPF_IMM A <- k BPF_LD+BPF_MEM A <- M[k] BPF_LDX These instructions load a value into the index register. Note that the addressing modes are more retricted than those of the accumulator loads, but they include BPF_MSH, a hack for efficiently loading the IP header length. BPF_LDX+BPF_W+BPF_IMM X <- k BPF_LDX+BPF_W+BPF_MEM X <- M[k] BPF_LDX+BPF_W+BPF_LEN X <- len BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf) BPF_ST This instruction stores the accumulator into the scratch memory. We do not need an addressing mode since there is only one possibility for the destination. BPF_ST M[k] <- A BPF_STX This instruction stores the index register in the scratch memory store. BPF_STX M[k] <- X BPF_ALU The alu instructions perform operations between the accumulator and index register or constant, and store the result back in the accumulator. For binary operations, a source mode is required (BPF_K or BPF_X). BPF_ALU+BPF_ADD+BPF_K A <- A + k BPF_ALU+BPF_SUB+BPF_K A <- A - k BPF_ALU+BPF_MUL+BPF_K A <- A * k BPF_ALU+BPF_DIV+BPF_K A <- A / k BPF_ALU+BPF_AND+BPF_K A <- A & k BPF_ALU+BPF_OR+BPF_K A <- A | k BPF_ALU+BPF_LSH+BPF_K A <- A << k BPF_ALU+BPF_RSH+BPF_K A <- A >> k BPF_ALU+BPF_ADD+BPF_X A <- A + X BPF_ALU+BPF_SUB+BPF_X A <- A - X BPF_ALU+BPF_MUL+BPF_X A <- A * X BPF_ALU+BPF_DIV+BPF_X A <- A / X BPF_ALU+BPF_AND+BPF_X A <- A & X BPF_ALU+BPF_OR+BPF_X A <- A | X BPF_ALU+BPF_LSH+BPF_X A <- A << X BPF_ALU+BPF_RSH+BPF_X A <- A >> X BPF_ALU+BPF_NEG A <- -A BPF_JMP The jump instructions alter flow of control. Conditional jumps compare the accumulator against a constant (BPF_K) or the index register (BPF_X). If the result is true (or non-zero), the true branch is taken, otherwise the false branch is taken. Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. However, the jump always (BPF_JA) opcode uses the 32 bit k field as the offset, allowing arbi- trarily distant destinations. All conditionals use unsigned comparison conventions. BPF_JMP+BPF_JA pc += k BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf BPF_RET The return instructions terminate the filter program and specify the amount of packet to accept (i.e., they return the truncation amount). A return value of zero indicates that the packet should be ignored. The return value is either a constant (BPF_K) or the accumulator (BPF_A). BPF_RET+BPF_A accept A bytes BPF_RET+BPF_K accept k bytes BPF_MISC The miscellaneous category was created for anything that doesn't fit into the above classes, and for any new instructions that might need to be added. Currently, these are the register transfer intructions that copy the index register to the accumulator or vice versa. BPF_MISC+BPF_TAX X <- A BPF_MISC+BPF_TXA A <- X The BPF interface provides the following macros to facilitate array initializers: BPF_STMT(opcode, operand) and BPF_JUMP(opcode, operand, true_offset, false_offset) EXAMPLES The following filter is taken from the Reverse ARP Daemon. It accepts only Reverse ARP requests. struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + sizeof(struct ether_header)), BPF_STMT(BPF_RET+BPF_K, 0), }; This filter accepts only IP packets between host 128.3.112.15 and 128.3.112.35. struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; Finally, this filter returns only TCP finger packets. We must parse the IP header to reach the TCP header. The BPF_JSET instruction checks that the IP fragment offset is 0 so we are sure that we have a TCP header. struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; bsdsocket.library/bpf_open bsdsocket.library/bpf_open NAME bpf_open - open a packet filter channel SYNOPSIS handle = bpf_open(channel) D0 D0 long bpf_open(long channel); FUNCTION The bpf_open() call will attempt to allocate a packet filter which can later be attached to an interface. How many channels are available and whether this "bsdsocket.library" version supports the packet filter mechanism in the first place can be queried using the SocketBaseTagList() function with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. The Berkeley Packet Filter provides a raw interface to data link layers in a protocol independent fashion. All packets on the network, even those destined for other hosts, are accessible through this mechanism. After opening the device, the file descriptor must be bound to a specific network interface with the BIOSETIF ioctl. A given interface can be shared be multiple listeners, and the filter underlying each descriptor will see an identical packet stream. A separate device file is required for each channel. If a file is in use, the open will fail and errno will be set to EBUSY. Associated with each open instance of a bpf file is a user-settable packet filter. Whenever a packet is received by an interface, all file descriptors listening on that interface apply their filter. Each descriptor that accepts the packet receives its own copy. Reads from these files return the next group of packets that have matched the filter. To improve performance, the buffer passed to read must be the same size as the buffers used internally by bpf. This size is returned by the BIOCGBLEN bpf_ioctl(), and under BSD, can be set with BIOCSBLEN. Note that an individual packet larger than this size is necessarily truncated. The packet filter will support any link level protocol that has fixed length headers. Currently, only Ethernet, SLIP and PPP drivers have been modified to interact with bpf. Since packet data is in network byte order, applications should use the byteorder macros to extract multi-byte values. A packet can be sent out on the network by writing to a bpf file descriptor. The writes are unbuffered, meaning only one packet can be processed per write. Currently, only writes to Ethernets and SLIP links are supported. INPUTS channel -- Index number of the channel to allocate, or -1 to allocate the next available channel. If a channel number is requested, it must be a non-negative integer that is smaller than the maximum number of channels this "bsdsocket.library" version supports. RESULT A channel handle > 0 is returned if the call succeeds, -1 if it fails. NOTES The bpf_open() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. The packet filter channel you allocate will be associated with the library base. When no longer needed, it should be released with the bpf_close() call. It will be automatically closed when the library is closed. ERRORS The call succeeds unless: [ENXIO] The channel index number does not refer to a valid packet filter channel. [EBUSY] This channel is already in use; try a different number. SEE ALSO bpf_close(), bpf_read(), bpf_write(), bpf_set_notify_mask(), bpf_set_interrupt_mask(), bpf_ioctl(), bpf_data_waiting() bsdsocket.library/bpf_read bsdsocket.library/bpf_read NAME bpf_read - read data from a packet filter channel SYNOPSIS nbytes = bpf_read(handle, buffer, len) D0 D0 A0 D1 long bpf_read(long handle,void *buffer,long len); FUNCTION The bpf_read() call will attempt to read packet data from a filter channel. If there is no data currently available for reading, this function will block until sufficient data has arrived, the read was interrupted or a timeout has elapsed. The duration of the timeout can be changed using the bpf_ioctl() function and the BIOCSRTIMEOUT command. INPUTS handle -- Handle number returned by previous call to bpf_open(). buffer -- Points to the memory where the data will be copied to. len -- Number of bytes to read; this must be exactly the same number the packet filter uses for buffering. This number can be set and read with the bpf_ioctl() function and the BIOCGBLEN/BIOCSBLEN commands. RESULT The number of bytes read is returned if the call succeeds, -1 if it fails. BPF HEADER The following structure is prepended to each packet returned by bpf_read(): struct bpf_hdr { struct timeval bh_tstamp; u_long bh_caplen; u_long bh_datalen; u_short bh_hdrlen; }; The fields, whose values are stored in host order, and are: bh_tstamp The time at which the packet was processed by the packet filter. bh_caplen The length of the captured portion of the packet. This is the minimum of the truncation amount specified by the filter and the length of the packet. bh_datalen The length of the packet off the wire. This value is independent of the truncation amount specified by the filter. bh_hdrlen The length of the BPF header, which may not be equal to sizeof(struct bpf_hdr). The bh_hdrlen field exists to account for padding between the header and the link level protocol. The purpose here is to guarantee proper alignment of the packet data structures, which is required on alignment sensitive architectures and and improves performance on many other architectures. The packet filter insures that the bpf_hdr and the network layer header will be word aligned. Suitable precautions must be taken when accessing the link layer protocol fields on alignment restricted machines. (This isn't a problem on an Ethernet, since the type field is a short falling on an even offset, and the addresses are probably accessed in a bytewise fashion). Additionally, individual packets are padded so that each starts on a word boundary. This requires that an application has some knowledge of how to get from packet to packet. The macro BPF_WORDALIGN is defined in to facilitate this process. It rounds up its argument to the nearest word aligned value (where a word is BPF_ALIGNMENT bytes wide). For example, if `p' points to the start of a packet, this expression will advance it to the next packet: p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) For the alignment mechanisms to work properly, the buffer passed to bpf_read() must itself be word aligned. AllocMem() and AllocVec() will always return an aligned buffer. NOTES The bpf_read() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. ERRORS The call succeeds unless: [ENXIO] The channel handle does not refer to a valid packet filter channel. [EPERM] You are not the owner of this channel. [EINVAL] The number of bytes to read does not exactly match the filter's buffer size. [EINTR] An interrupt signal was received while the read command was still waiting for new data to arrive. SEE ALSO bpf_open(), bpf_close(), bpf_write(), bpf_set_notify_mask(), bpf_set_interrupt_mask(), bpf_ioctl(), bpf_data_waiting() bsdsocket.library/bpf_set_interrupt_masksocket.library/bpf_set_interrupt_mask NAME bpf_set_interrupt_mask - choose which signals will cause the bpf_read() call to be interrupted SYNOPSIS success = bpf_set_interrupt_mask(handle, mask) D0 D0 D1 long bpf_set_interrupt_mask(long handle, unsigned long mask); FUNCTION The bpf_set_interrupt_mask() call allows you to choose which signals will cause the bpf_read() call to be interrupted when received. By default, bpf_open() resets this signal mask to 0, which means that no signal will interrupt bpf_read(). INPUTS handle -- Handle number returned by previous call to bpf_open(). mask -- The signal mask to hand to exec.library/Wait(); a value of 0 disables this mechanism. RESULT A 0 return value indicates success; -1 indicates an error. NOTES The bpf_set_interrupt_mask() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. ERRORS The call succeeds unless: [ENXIO] The channel handle does not refer to a valid packet filter channel. [EPERM] You are not the owner of this channel. SEE ALSO bpf_open(), bpf_close(), bpf_read(), bpf_write(), bpf_set_notify_mask(), bpf_ioctl(), bpf_data_waiting(), exec.library/Signal, exec.library/Wait bsdsocket.library/bpf_set_notify_mask bsdsocket.library/bpf_set_notify_mask NAME bpf_set_notify_mask - choose the signals to send when new packet data is available for reading SYNOPSIS success = bpf_set_notify_mask(handle, mask) D0 D0 D1 long bpf_set_notify_mask(long handle, unsigned long mask); FUNCTION The bpf_set_notify_mask() call allows you to choose whether you want to receive a notification signal whenever there is new packet data to be read with bpf_read() becomes available. By default, bpf_open() resets this signal to 0, which means that no notification signal will be sent. INPUTS handle -- Handle number returned by previous call to bpf_open(). mask -- The signal mask to hand to exec.library/Signal(); a value of 0 disables the notification. RESULT A 0 return value indicates success; -1 indicates an error. NOTES The bpf_set_notify_mask() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. ERRORS The call succeeds unless: [ENXIO] The channel handle does not refer to a valid packet filter channel. [EPERM] You are not the owner of this channel. SEE ALSO bpf_open(), bpf_close(), bpf_read(), bpf_write(), bpf_set_interrupt_mask(), bpf_ioctl(), bpf_data_waiting(), exec.library/Signal bsdsocket.library/bpf_write bsdsocket.library/bpf_write NAME bpf_write - write data to an interface associated with a packet filter channel SYNOPSIS nbytes = bpf_write(handle, buffer, len) D0 D0 A0 D1 long bpf_write(long handle,void *buffer,long len); FUNCTION The bpf_write() call will write data to the interface attached to this channel. You have to provide a complete link level frame, which for an Ethernet interface includes the Ethernet header. The data you provide will be committed to the wire exactly as you write it. INPUTS handle -- Handle number returned by previous call to bpf_open(). buffer -- Points to the memory to copy the data from. len -- Number of bytes to write. RESULT The number of bytes written is returned if the call succeeds, -1 if it fails. NOTES The bpf_write() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, you must query the number of filter channels supported by it using SocketBaseTagList() with the SBTC_NUM_PACKET_FILTER_CHANNELS tag. ERRORS The call succeeds unless: [ENXIO] The channel handle does not refer to a valid packet filter channel, or the channel is not attached to an interface. [EIO] The packet does not fit into a single memory chunk. [ENOBUFS] Not enough memory for the packet to be sent. [EPERM] You are not the owner of this channel. [EMSGSIZE] The number of bytes to be written exceeds the interface's maximum transfer unit. SEE ALSO bpf_open(), bpf_close(), bpf_read(), bpf_set_notify_mask(), bpf_set_interrupt_mask(), bpf_ioctl(), bpf_data_waiting() bsdsocket.library/ChangeRoadshowData bsdsocket.library/ChangeRoadshowData NAME ChangeRoadshowData - Change internal Roadshow configuration data SYNOPSIS success = ChangeRoadshowData(list,name,length,data) D0 A0 A1 D0 A2 BOOL ChangeRoadshowData(struct List *list,STRPTR name, ULONG length,APTR data); FUNCTION Several internal options control how the TCP/IP stack works. These do not normally need to be changed, but there are times when you might want to override or check them. ChangeRoadshowData() will change a configuration data item. INPUTS list -- The pointer you received from ObtainRoadshowData() name -- Pointer to a NUL-terminated string which gives the name of the option to change. Option names are not case-sensitive. length -- Number of bytes in the option data to change the current settings to. data -- Pointer to the option data to change the current settings to. RESULT success -- TRUE if the option could be changed, FALSE otherwise. ERRORS The ChangeRoadshowData() call fails if: [EINVAL] The list parameter you supplied is invalid. [EACCES] You did not call ObtainRoadshowData() with the ORD_WriteAccess parameter. [ENOENT] The option you wanted to change is not known by the name you gave. [ENOSPC] The size of the option data you specified is not supported, e.g. the wrong size or there is not enough space available to store it. [EPERM] You tried to modify a read-only option. OPTIONS Here is a brief list of options that may be supported by your Roadshow installation. bpf.bufsize The size of the Berkeley Packet Filter buffer. icmp.maskrepl Controls if the ICMP layer responds to mask requests. This can be 1 (accept) or 0 (ignore). icmp.processecho Controls if the ICMP layer responds to echo requests. This can be 0 (accept), 1 (ignore) or 2 (drop). icmp.procesststamp Controls if the ICMP layer responds to time stamp requests. This can be 0 (accept), 1 (ignore) or 2 (drop). ip.defttl Controls the default time-to-live value of IP packets generated. ip.forwarding Controls if IP packets may be forwarded or not. This can be 1 (forward) or 0 (drop). ip.sendredirects Controls if ICMP redirect messages may be generated. This can be 1 (yes) or 0 (no). ip.subnetsarelocal Controls if the Internet addresses of directly connected hosts should be considered local, or if this also applies to hosts on the same subnet. This can be 1 (subnets are local) or 0 (they are not). task.controller.priority Selects the priority at which the network I/O controller Task runs. The priority can affect overall network performance. tcp.do_rfc1323 Controls whether or not the TCP extensions for high performance (RFC1323) should be enabled or not. Specifically, this covers round trip time measurement and the TCP window scale option. This can be 1 (enable) or 0 (disable). tcp.do_timestamps Controls whether or not the round trip time measurement feature should be enabled if the tcp.do_rfc1323 option is enabled. This can be 1 (enable) or 0 (disable). tcp.do_win_scale Controls whether or not the TCP window scale option should be enabled if the tcp.do_rfc1323 option is enabled. This can be 1 (enable) or 0 (disable). tcp.mssdflt Controls the default TCP maximum segment size value. tcp.recvspace Controls the size of the default TCP receive buffer. tcp.rttdflt Controls the default TCP retransmit time value. tcp.sendspace Controls the size of the default TCP transmit buffer. tcp.use_mssdflt_for_remote Controls if the TCP protocol should use a smaller maximum segment size value for packets sent to hosts which are not in the local network. This can be 1 (yes) or 0 (no). udp.cksum Controls if checksums should be calculated over UDP datagrams to be sent and verified for UDP datagrams received. This can be 1 (yes) or 0 (no). udp.recvspace Controls the size of the default UDP receive buffer. udp.sendspace Controls the size of the default UDP transmit buffer. NOTES The ChangeRoadshowData() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ROADSHOWDATA_API tag with the SocketBaseTagList() function. SEE ALSO ObtainRoadshowData(), ChangeRoadshowData() bsdsocket.library/CloseSocket bsdsocket.library/CloseSocket NAME CloseSocket - delete a socket descriptor SYNOPSIS success = CloseSocket(s) D0 D0 long CloseSocket(long s); FUNCTION The CloseSocket() call deletes a descriptor from the per-library object reference table. If this is the last reference to the underlying object, the object will be deactivated. For example, on the last close of a socket() associated naming information and queued data are discarded. When a library base is closed, all associated socket descriptors are freed, but since there is a limit on active descriptors per library base, the CloseSocket() function call is useful when a large quantity of file descriptors are being handled. RESULT Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the global integer variable errno is set to indicate the error. ERRORS CloseSocket() will fail if: [EBADF] s is not an active socket descriptor. [EINTR] An interrupt was received. SEE ALSO accept(), socket(), IoctlSocket() bsdsocket.library/ConfigureInterfaceTagList.library/ConfigureInterfaceTagList NAME ConfigureInterfaceTagList - Configure an interface SYNOPSIS success = ConfigureInterfaceTagList(name,tags) D0 A0 A1 long ConfigureInterfaceTagList(STRPTR name,struct TagItem *tags); long ConfigureInterfaceTags(STRPTR name,...); FUNCTION This function is for changing the configuration of an interface previously added with AddInterfaceTagList(), such as setting interface addresses, status and routing metrics. INPUTS name -- Name of the interface to query/configure. This name cannot be longer than 15 characters. tags -- Pointer to a 'struct TagItem' list. TAGS IFC_Address (STRPTR) - Address to assign to this interface; this must be a NUL-terminated string which can hold a host name to be resolved or an IP address in dotted-decimal notation (per RFC1700). IFC_NetMask (STRPTR) - Network mask to assign to this interface; this must be a NUL-terminated string. IFC_DestinationAddress (STRPTR) - Address of the other end of a point-to-point link. This must be a NUL-terminated string which can hold a host name to be resolved or an IP address in dotted-decimal notation (per RFC1700). This tag requires the IFC_Address tag to be present and only works for point-to-point interfaces. IFC_BroadcastAddress (STRPTR) - Broadcast address this interface should use; this only works for interfaces which support broadcasts in the first place, such as Ethernet hardware. This must be specified as NUL-terminated string in dotted-decimal notation (per RFC1700). IFC_Metric (LONG) - The routing metric of this interface, as used by the routing protocol. IFC_AddAliasAddress (STRPTR) - Additional address to associate this interface with. This must be a NUL-terminated string which can hold a host name to be resolved or an IP address in dotted-decimal notation (per RFC1700). This tag and the IFC_DeleteAliasAddress tag are mutually exclusive. IFC_DeleteAliasAddress (STRPTR) - An alias address to remove from this interface. This must be a NUL-terminated string which can hold a host name to be resolved or an IP address in dotted-decimal notation (per RFC1700). This tag and the IFC_AddAliasAddress tag are mutually exclusive. IFC_State (LONG) - State this interface should be set to. This must be one of the following options: SM_Down The stack will no longer attempt to transmit messags through this interface. However, the underlying SANA-II device driver may still be connected to the network. SM_Up The stack will attempt to transmit messages through this interface. However, the underlying SANA-II device driver may not be connected to the network yet. SM_Offline Same as 'SM_Down', but also sends an 'S2_OFFLINE' command to the underlying SANA-II device first. SM_Online Same as 'SM_Up', but tries to send an 'S2_ONLINE' command to the underlying SANA-II device first; if the command succeeds, the other necessary configuration operations will take place. If it fails, then this function will return with an error code set and no further configuration will have been done. IFC_GetPeerAddress (BOOL) - Try to obtain the interface's local and its point to point partner's address. This only works for devices implementing point to point protocols like SLIP or PPP. The addresses will be copied to the interface's default address (overriding the IFC_Address tag) and the interface's destination address (overriding the IFC_DestinationAddress tag). The interface's net mask will be configured according to the default address. IFC_GetDNS (BOOL) - Try to obtain the primary and secondary domain name server addresses, if these are known to the interface. This only works for devices implementing PPP. The addresses will be stored for future reference, if successful. IFC_AssociatedRoute (BOOL) - Tag this interface as having a route attached which should be removed should the interface go down or offline. IFC_AssociatedDNS (BOOL) - Tag this interface as making domain name servers available which should be removed should the interface go down or offline. IFC_ReleaseAddress (BOOL) - If this interface's address was dynamically bound (via DHCP or BOOTP), it will be released and the interface will be taken out of service. IFC_SetDebugMode (BOOL) - Enable or disable debugging mode for this interface. IFC_Complete (BOOL) -- Indicate that the configuration for this interface is now complete. This has the effect of causing the default route configuration file to be read and processed for the first time. IFC_LimitMTU (ULONG) - You can limit the size of the maximum transmission unit (MTU) configured for this interface. Normally, this value is predefined by the hardware driver, but you can request that a smaller size is used. This can help if, in order to route packets properly, an artificial limit is imposed on the maximum packet size. By default the MTU value provided by the hardware driver is used. Before the maximum transmission unit size is limited, the hardware MTU settings will be reread and taken into account. RESULT success -- 0 for success, -1 for failure; the failure code will be stored in the 'errno' variable. NOTES The ConfigureInterfaceTagList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. This function is intended to be a simplified, specialized front end to the underlying interface socket API. If you want more than this function can do for you, use the interface socket API. The IFC_GetPeerAddress and IFC_GetDNS tags require that the underlying device driver supports the SANA-IIR4 extensions, which at this time of writing not many drivers do. Take care. SEE ALSO AddInterfaceTagList(), QueryInterfaceTagList() bsdsocket.library/connect bsdsocket.library/connect NAME connect - initiate a connection on a socket SYNOPSIS #include #include success = connect(s, name, namelen) D0 D0 A0 D1 long connect(long s, struct sockaddr *name, long namelen); FUNCTION The parameter s is a socket. If it is of type SOCK_DGRAM, this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket. The other socket is specified by name, which is an address in the communications space of the socket. Each communications space interprets the name parameter in its own way. Generally, stream sockets may successfully connect() only once; datagram sockets may use connect() multiple times to change their association. Datagram sockets may dissolve the association by connecting to an invalid address, such as a null address. RESULT If the connection or binding succeeds, 0 is returned. Otherwise a -1 is returned, and a more specific error code is stored in errno. ERRORS The connect() call fails if: [EBADF] S is not a valid descriptor. [ENOTSOCK] S is a descriptor for a file, not a socket. [EADDRNOTAVAIL] The specified address is not available on this machine. [EAFNOSUPPORT] Addresses in the specified address family cannot be used with this socket. [EISCONN] The socket is already connected. [ETIMEDOUT] Connection establishment timed out without establishing a connection. [ECONNREFUSED] The attempt to connect was forcefully rejected. [ENETUNREACH] The network isn't reachable from this host. [EADDRINUSE] The address is already in use. [EFAULT] The name parameter specifies an area outside the process address space. [EINPROGRESS] The socket is non-blocking and the connection cannot be completed immediately. It is possible to WaitSelect() for completion by selecting the socket for writing. [EALREADY] The socket is non-blocking and a previous connection attempt has not yet been completed. SEE ALSO accept(), WaitSelect(), socket(), getsockname() bsdsocket.library/CreateAddrAllocMessageAcket.library/CreateAddrAllocMessageA NAME CreateAddrAllocMessageA - Create a message to be used with the BeginInterfaceConfig() DHCP interface configuration routine. SYNOPSIS error = CreateAddrAllocMessageA(version,protocol,interface_name, D0 D0 D1 A0 result_ptr, tags) A1 A2 LONG CreateAddrAllocMessageA(LONG version,LONG protocol, STRPTR interface_name, struct AddressAllocationMessage * result_ptr, struct TagItem * tags); LONG CreateAddrAllocMessage(LONG version, LONG protocol, STRPTR interface_name, struct AddressAllocationMessage * result_ptr, ...); FUNCTION The AddressAllocationMessage used by the BeginInterfaceConfig() DHCP configuration routine needs to be created and properly initialized before it can be used. While this initialization can be performed manually, it is recommended that you use the CreateAddrAllocMessageA() routine instead which will fill in proper defaults and can allocate extra memory for data to be returned by the configuration process. INPUTS version -- Data structure version; this must be AAM_VERSION (see the BeginInterfaceConfig() autodoc for more). protocol -- Configuration protocol type, either AAMP_BOOTP or AAMP_DHCP. interface_name -- The name of the network interface to be configured. result_ptr -- Reference to a pointer which will be filled with the address of the AddressAllocationMessage created. tags -- Pointer to a tag item list which contains more information on how the AddressAllocationMessage should be filled in. TAGS CAAMTA_Timeout (ULONG) - Number of seconds to wait for a BOOTP/DHCP server to respond. Due to how the configuration process works, the timeout must be at least 10 seconds long. If it is shorter, it is automatically extended to 10 seconds. Default for this option is 10 seconds. CAAMTA_LeaseTime (ULONG) - This option is relevant only for DHCP. It allows you to specify the interface address lease time to request from the server. The default is DHCP_DEFAULT_LEASE_TIME, which accepts the server's choice. The value DHCP_INFINITE_LEASE_TIME will attempt to bind the interface address permanently. All other values refer to the number of seconds the lease should be allocated. Note that the server may choose to ignore your preferred lease time. CAAMTA_RequestedAddress (ULONG) - A DHCP client can make a wish, as to which IP address should be allocated for it. This is where you provide your choice. Note that the server may ignore your wish. Make sure that your application does not assume that it is always allocated the IP address you requested. Default for this option is to accept the server's coice. CAAMTA_ClientIdentifier (STRPTR) - Allocating an IP address for a DHCP client is not that helpful if the client cannot be referred to by its name after an address has been assigned to it. You can request a name to be bound to the IP address to assign by specifying it here. The name will be duplicated and stored in the allocation message. The name must be at least 2 characters long and it cannot be longer than 255 characters. Default for this option is to accept the server's choice. CAAMTA_NAKMessageSize (LONG) - Size of the buffer to reserve for the NAK message the server may return (in bytes). This will fill in the 'aam_NAKMessage' and 'aam_NAKMessageSize' members of the allocation message. Default for this option is not to reserve any memory for the NAK message buffer. CAAMTA_RouterTableSize (LONG) - This is where you specify for how many router table entries you want memory to be allocated. This will fill in the 'aam_RouterTable' and 'aam_RouterTableSize' members of the allocation message. Default for this option is not to reserve any memory for the router table. CAAMTA_DNSTableSize (LONG) - This is where you specify for how many DNS address table entries you want memory to be allocated. This will fill in the 'aam_DNSTable' and 'aam_DNSTableSize' members of the allocation message. Default for this option is not to reserve any memory for the DNS address table. CAAMTA_StaticRouteTableSize (LONG) - This is where you specify for how many static route address table entries you want memory to be allocated. This will fill in the 'aam_StaticRouteTable' and 'aam_StaticRouteTableSize' members of the allocation message. Default for this option is not to reserve any memory for the static route address table. CAAMTA_HostNameSize (LONG) - How many bytes to reserve for the host name the server may provide for the client. This will fill in the 'aam_HostName' and 'aam_HostNameSize' members of the address allocation message. Default for this option is not to reserve any memory for the host name. CAAMTA_DomainNameSize (LONG) - How many bytes to reserve for the domain name the server may provide for the client. This will fill in the 'aam_DomainName' and 'aam_DomainNameSize' members of the address allocation message. Default for this option is not to reserve any memory for the domain name. CAAMTA_BOOTPMessageSize (LONG) - How many bytes to reserve for the BOOTP message the server will return. This will fill in the 'aam_BOOTPMessage' and 'aam_BOOTPMessageSize' members of the address allocation message. Default for this option is not to reserve any memory for the BOOTP message. CAAMTA_RecordLeaseExpiration (BOOL) - If set to TRUE, memory for a DateStamp in the 'aam_LeaseExpires' member of the address allocation message will be reserved, which later will hold the time and date when the DHCP lease expires. Default for this option is not to reserve any memory for the lease expiration date stamp. CAAMTA_ReplyPort (struct MsgPort *) - You can have the MsgPort stored in the allocation message the message should be returned to when the allocation process has finished. RESULT error -- If the creation of the address allocation message failed for one reason or another, then this routine will return a non-zero error code, otherwise the result will be zero. result_ptr -- If successful, a pointer to the newly allocated address allocation message will be stored in the reference this parameter points to. ERRORS CAAME_Success The address allocation message was allocated and filled in successfully. This is not an error. CAAME_Invalid_result_ptr The 'result_ptr' parameter you provided is not valid, e.g. it is NULL. CAAME_Not_enough_memory The routine ran out of memory whilst trying to fill in your address allocation message. CAAME_Invalid_version The version number you requested is not supported. CAAME_Invalid_protocol The configuration protocol you requested is not supported. CAAME_Invalid_interface_name The interface name you provided is not valid, e.g. you provided a NULL pointer, or the name is empty. CAAME_Interface_not_found The interface whose name you provided could not be found. CAAME_Invalid_client_identifier The client identifier you provided is not valid, e.g. empty. CAAME_Client_identifier_too_short The client identifier you provided is too short. CAAME_Client_identifier_too_long The client identifier you provided is too long. NOTES The BeginInterfaceConfig() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. SEE ALSO BeginInterfaceConfig() DeleteAddrAllocMessage() bsdsocket.library/DeleteAddrAllocMessagesocket.library/DeleteAddrAllocMessage NAME DeleteAddrAllocMessage - Release the memory allocation for an address allocation message created by CreateAddrAllocMessageA(). SYNOPSIS DeleteAddrAllocMessage(message) A0 VOID DeleteAddrAllocMessage(struct AddressAllocationMessage * m); FUNCTION This routine is the counterpart to CreateAddrAllocMessageA(). When the message is no longer used, it should be deallocated by calling this routine. INPUTS message -- An address allocation message as created by CreateAddrAllocMessageA(). Passing a NULL pointer in place of a valid message address is harmless. NOTES The BeginInterfaceConfig() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. Never delete a message that is still in use by the configuration process, or strange things will happen, such as operating system crashes. This routine can only deallocate address allocation messages created by CreateAddrAllocMessageA() and will not work with anything else. SEE ALSO BeginInterfaceConfig() CreateAddrAllocMessageA() bsdsocket.library/DeleteRouteTagList bsdsocket.library/DeleteRouteTagList NAME DeleteRouteTagList - Remove entries from the networking routing tables SYNOPSIS success = DeleteRouteTagList(tags) D0 A0 long DeleteRouteTagList(struct TagItem *tags); long DeleteRouteTags(Tag tag1,...); FUNCTION This function is for manipulating the networking routing tables by removing entries from them. INPUTS tags -- Pointer to a 'struct TagItem' list. TAGS RTA_Destination (STRPTR) -- The destination address of the route previously added, which must be specified as a NUL-terminated string. The string can contain a host name to be resolved or an IP address in dotted-decimal notation (per RFC1700). The use of the RTA_Destination parameter excludes the user of the RTA_DefaultGateway parameter. RTA_DefaultGateway (STRPTR) -- The address of the default gateway all packets were forwarded to which could not be sent along any other known route. This must be a NUL-terminated string referring to a host name to be resolved or an IP address in dotted-decimal notation (per RFC1700). The use of the RTA_DefaultGateway parameter excludes the user of the RTA_Destination parameter. RESULT success -- 0 for success, -1 for failure; the failure code will be stored in the 'errno' variable. NOTES The DeleteRouteTagList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ROUTING_API tag with the SocketBaseTagList() function. This function is intended to be a simplified, specialized front end to the underlying routing socket API. If you want more than this function can do for you, use the routing socket API. Take care, as this functionality is not present in the original AmiTCP implementation. SEE ALSO AddRouteTagList(), route bsdsocket.library/Dup2Socket bsdsocket.library/Dup2Socket NAME Dup2Socket - duplicate a socket descriptor SYNOPSIS s = Dup2Socket(old_socket, new_socket) D0 D0 D1 long Dup2Socket(long old_socket, long new_socket); FUNCTION Dup2Socket() duplicates an existing socket descriptor and returns its value to the caller. The argument old_socket is a small nonnegative integer index in the per-library base descriptor table. The value must be less than the size of the table, which is returned by getdtablesize(). The new_socket parameter refers to the socket which should be used as the new socket descriptor number. If that value refers to an existing socket, then this socket will be closed before it is used. If the new_socket parameter is -1, then the lowest numbered descriptor currently not in use will be claimed. RESULT The value -1 is returned if an error occurs; otherwise, the new socket descriptor value is returned. ERRORS Dup2Socket fails if: [EBADF] old_socket or new_socket is not a valid active descriptor, and new_socket is not -1. [EMFILE] Too many descriptors are active. SEE ALSO accept(), CloseSocket(), IoctlSocket(), socket(), getdtablesize() bsdsocket.library/endnetent bsdsocket.library/endnetent NAME endnetent - get network entry SYNOPSIS #include endnetent() void endnetent(void); FUNCTION The endnetent() function closes the net database. SEE ALSO getnetent(), getnetbyaddr(), getnetbyname(), setnetent() BUGS The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. NOTES The endnetent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/endprotoent bsdsocket.library/endprotoent NAME endprotoent - get protocol entry SYNOPSIS #include endprotoent() void endprotoent(void); FUNCTION The endprotoent() function closes the protocol database. SEE ALSO getprotoent(), getprotobynumber(), getprotobyname(), setprotoent() BUGS These functions use a static data space; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet protocols are currently understood. NOTES The endprotoent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/endservent bsdsocket.library/endservent NAME endservent - get service entry SYNOPSIS #include endservent() void endservent(void); FUNCTION The endservent() function closes the service database. SEE ALSO getservent(), getservbyname(), getservbyport(), setservent() NOTES The endservent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/Errno bsdsocket.library/Errno NAME Errno - get error value after unsuccessful function call SYNOPSIS error = Errno() D0 long Errno(void); FUNCTION This function is deprecated; SocketBaseTags() with the SBTC_ERRNO tag should be used instead. After a function call has failed, the Errno() function will return the error code associated with the cause of the failure. RESULT The error code set by the previous function call. SEE ALSO SetErrnoPtr() bsdsocket.library/FreeRouteInfo bsdsocket.library/FreeRouteInfo NAME FreeRouteInfo - Release information obtained by GetRouteInfo(). SYNOPSIS FreeRouteInfo(table) A0 VOID FreeRouteInfo(struct rt_msghdr *table); FUNCTION This function is the counterpart to GetRouteInfo() in that it releases the memory allocated for the copy of the routing table information previously returned. INPUTS table -- Pointer to the routing table information as returned by GetRouteInfo(). This parameter can be NULL in which case this routine does nothing. NOTES The FreeRouteInfo() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ROUTING_API tag with the SocketBaseTagList() function. SEE ALSO GetRouteInfo(), route bsdsocket.library/GetDefaultDomainName bsdsocket.library/GetDefaultDomainName NAME GetDefaultDomainName - Retrieve the domain name that will be added to the end of host names which lack a domain name. SYNOPSIS success = GetDefaultDomainName(buffer,buffer_size) D0 A0 D0 BOOL GetDefaultDomainName(STRPTR buffer,LONG buffer_size); FUNCTION If no domain name is part of a host name, a default domain name can be added to it if the host name lookup fails. This is normally controlled by the name server configuration file but may be overridden either through an environment variable or a call to SetDefaultDomainName(). The domain name configured through SetDefaultDomainName() can be queried via GetDefaultDomainName(). INPUTS buffer -- The string buffer to copy the default domain name to. buffer_size -- Number of bytes in the string buffer to copy the default domain name to; this must include the terminating NUL byte. If the default domain name is larger than will fit into the buffer, then the name will be truncated. RESULT success -- FALSE if the default domain name is not set, TRUE otherwise. NOTES The GetDefaultDomainName() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_DNS_API tag with the SocketBaseTagList() function. SEE ALSO SetDefaultDomainName(), SocketBaseTagList() bsdsocket.library/getdtablesize bsdsocket.library/getdtablesize NAME getdtablesize - get descriptor table size SYNOPSIS nfds = getdtablesize() D0 int getdtablesize(void); FUNCTION This function is deprecated; SocketBaseTags() with the SBTC_DTABLESIZE tag should be used instead. Each library base has a fixed size descriptor table, which is guaranteed to have at least 20 slots. The entries in the descriptor table are numbered with small integers starting at 0. The call getdtablesize() returns the size of this table. RESULT The size of the descriptor table. SEE ALSO CloseSocket(), socket(), WaitSelect(), SocketBaseTagList() bsdsocket.library/gethostbyaddr bsdsocket.library/gethostbyaddr NAME gethostbyaddr - get network host entry SYNOPSIS #include extern long h_errno; hostent = gethostbyaddr(addr, len, type) D0 A0 D0 D1 struct hostent * gethostbyaddr(char *addr, long len, long type); FUNCTION The gethostbyname() and gethostbyaddr() functions each return a pointer to an object with the following structure describing an internet host referenced by name or by address, respectively. This structure contains either the information obtained from the name server, or broken-out fields from a line in the local hosts database. If the local name server is not running these routines do a lookup in the local hosts database. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ long h_addrtype; /* host address type */ long h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ The members of this structure are: h_name Official name of the host. h_aliases A zero terminated array of alternate names for the host. h_addrtype The type of address being returned; currently always AF_INET. h_length The length, in bytes, of the address. h_addr_list A zero terminated array of network addresses for the host. Host addresses are returned in network byte order. h_addr The first address in h_addr_list; this is for backward compatibility. When using the nameserver, gethostbyname() will search for the named host in the current domain and its parents unless the name ends in a dot. If the name contains no dot, and if the environment variable ``HOSTALIASES'' contains the name of an alias file, the alias file will first be searched for an alias matching the input name. RESULT Error return status from gethostbyname() and gethostbyaddr() is indicated by return of a null pointer. The external integer h_errno may then be checked to see whether this is a temporary failure or an invalid or unknown host. The variable h_errno can have the following values: HOST_NOT_FOUND No such host is known. TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. NO_DATA The requested name is valid but does not have an IP address; this is not a temporary error. This means that the name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name will result in an answer; for example, a mail-forwarder may be registered for this domain. BUGS These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet address format is currently understood. bsdsocket.library/gethostbyname bsdsocket.library/gethostbyname NAME gethostbyname - get network host entry SYNOPSIS #include extern long h_errno; hostent = gethostbyname(name) D0 A0 struct hostent * gethostbyname(char *name); FUNCTION The gethostbyname() and gethostbyaddr() functions each return a pointer to an object with the following structure describing an internet host referenced by name or by address, respectively. This structure contains either the information obtained from the name server, or broken-out fields from a line in the hosts database. If the local name server is not running these routines do a lookup in the local host database. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ long h_addrtype; /* host address type */ long h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ The members of this structure are: h_name Official name of the host. h_aliases A zero terminated array of alternate names for the host. h_addrtype The type of address being returned; currently always AF_INET. h_length The length, in bytes, of the address. h_addr_list A zero terminated array of network addresses for the host. Host addresses are returned in network byte order. h_addr The first address in h_addr_list; this is for backward compatibility. When using the nameserver, gethostbyname() will search for the named host in the current domain and its parents unless the name ends in a dot. If the name contains no dot, and if the environment variable ``HOSTALIASES'' contains the name of an alias file, the alias file will first be searched for an alias matching the input name. RESULT Error return status from gethostbyname() and gethostbyaddr() is indicated by return of a null pointer. The external integer h_errno may then be checked to see whether this is a temporary failure or an invalid or unknown host. The variable h_errno can have the following values: HOST_NOT_FOUND No such host is known. TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. NO_DATA The requested name is valid but does not have an IP address; this is not a temporary error. This means that the name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name will result in an answer; for example, a mail-forwarder may be registered for this domain. BUGS These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet address format is currently understood. bsdsocket.library/gethostid bsdsocket.library/gethostid NAME gethostid - get unique identifier of current host SYNOPSIS id = gethostid() D0 long gethostid(void); FUNCTION This function has been deprecated. gethostid() returns the 32-bit identifier for the current processor. NOTES This function should not be used in new code since its result is essentially unpredictable and depends upon the current state of the interfaces configured. RESULT 32-bit identifier for the current processor. SEE ALSO gethostname() BUGS 32 bits for the identifier is too small. bsdsocket.library/gethostname bsdsocket.library/gethostname NAME gethostname - get name of current host SYNOPSIS success = gethostname(name,namelen) D0 A0 D0 long gethostname(char *name, long namelen); FUNCTION gethostname() returns the standard host name for the current processor. The parameter namelen specifies the size of the name array. The returned name is null-terminated unless insufficient space is provided. NOTES This function will attempt to match the host's IP address, as obtained by querying the first interface that is online, against the host database. If that fails, it will attempt to perform a reverse name resolution. If that fails, it will query the 'HOSTNAME' environment variable. If that fails, it will return the name "localhost". RESULT If the call succeeds a value of 0 is returned. If the call fails, a value of -1 is returned and an error code is placed in the global location errno. ERRORS The following errors may be returned by this call: [EFAULT] The name or namelen parameter gave an invalid address. [EPERM] The caller tried to set the hostname and was not the superuser. SEE ALSO gethostid() BUGS Host names are limited to MAXHOSTNAMELEN (from ) characters, currently 256. bsdsocket.library/getnetbyaddr bsdsocket.library/getnetbyaddr NAME getnetbyaddr - get network entry SYNOPSIS #include netent = getnetbyaddr(net,type) D0 D0 D1 struct netent * getnetbyaddr(unsigned long net, long type); FUNCTION The getnetbyname() and getnetbyaddr() functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network data base. struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ long n_addrtype; /* net number type */ unsigned long n_net; /* net number */ }; The members of this structure are: n_name The official name of the network. n_aliases A zero terminated list of alternate names for the network. n_addrtype The type of the network number returned; currently only AF_INET. n_net The network number. Network numbers are returned in machine byte order. The getnetbyname() function and getnetbyaddr() sequentially search from the beginning of the file until a matching net name or net address and type is found, or until EOF is encountered. Network numbers are supplied in host order. RESULT Null pointer (0) returned on EOF or error. BUGS The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. bsdsocket.library/getnetbyname bsdsocket.library/getnetbyname NAME getnetbyname - get network entry SYNOPSIS #include netent = getnetbyname(name) D0 A0 struct netent * getnetbyname(char *name); FUNCTION The getnetbyname() and getnetbyaddr() functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network data base. struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ long n_addrtype; /* net number type */ unsigned long n_net; /* net number */ }; The members of this structure are: n_name The official name of the network. n_aliases A zero terminated list of alternate names for the network. n_addrtype The type of the network number returned; currently only AF_INET. n_net The network number. Network numbers are returned in machine byte order. The getnetbyname() function and getnetbyaddr() sequentially search from the beginning of the file until a matching net name or net address and type is found, or until EOF is encountered. Network numbers are supplied in host order. RESULT Null pointer (0) returned on EOF or error. BUGS The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. bsdsocket.library/getnetent bsdsocket.library/getnetent NAME getnetent - get network entry SYNOPSIS #include entry = getnetent() D0 struct netent * getnetent(void); FUNCTION The getnetent() function reads the next line of the net database, opening the database if necessary. RESULT Null pointer (0) returned on EOF or error. SEE ALSO endnetent(), getnetbyaddr(), getnetbyname(), setnetent() BUGS The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. NOTES The getnetent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/GetNetworkStatistics bsdsocket.library/GetNetworkStatistics NAME GetNetworkStatistics - Obtain network usage statistics SYNOPSIS length = GetNetworkStatistics(type,version,destination,size) D0 D0 D1 A0 D2 LONG GetNetworkStatistics(LONG type,LONG version, APTR destination,LONG size); FUNCTION This function will provide a local copy of internal statistics information maintained by the protocol stack. Different kinds of statistics are available, each covering different aspects of the implementation. INPUTS type -- The type of information to be returned. This must be one of NETSTATUS_icmp, NETSTATUS_igmp, NETSTATUS_ip, NETSTATUS_mb, NETSTATUS_mrt, NETSTATUS_rt, NETSTATUS_tcp, NETSTATUS_udp, NETSTATUS_tcp_sockets or NETSTATUS_udp_sockets. version -- Since the data structures to be returned can change as new protocol stack implementations are released, you must specify which version of the data structures you need to see. The version described in this documentation is 1. destination -- Points to the memory where the data should be stored. Pass a NULL pointer to find out how much memory would be required for a complete copy of the data you requested. size -- Number of bytes to copy from the internal data structures to the destination memory. TYPES NETSTATUS_icmp - Internet control message protocol statistics The statistics data will be of the following format: struct icmpstat { /* statistics related to icmp packets generated */ ULONG icps_error; /* # of calls to icmp_error */ ULONG icps_oldshort; /* no error 'cuz old ip too short */ ULONG icps_oldicmp; /* no error 'cuz old was icmp */ ULONG icps_outhist[ICMP_MAXTYPE + 1]; /* statistics related to input messages processed */ ULONG icps_badcode; /* icmp_code out of range */ ULONG icps_tooshort; /* packet < ICMP_MINLEN */ ULONG icps_checksum; /* bad checksum */ ULONG icps_badlen; /* calculated bound mismatch */ ULONG icps_reflect; /* number of responses */ ULONG icps_inhist[ICMP_MAXTYPE + 1]; }; NETSTATUS_igmp - Internet group management protocol statistics The statistics data will be of the following format: struct igmpstat { ULONG igps_rcv_total; /* total IGMP messages received */ ULONG igps_rcv_tooshort; /* received with too few bytes */ ULONG igps_rcv_badsum; /* received with bad checksum */ ULONG igps_rcv_queries; /* received membership queries */ ULONG igps_rcv_badqueries; /* received invalid queries */ ULONG igps_rcv_reports; /* received membership reports */ ULONG igps_rcv_badreports; /* received invalid reports */ ULONG igps_rcv_ourreports; /* received reports for our groups */ ULONG igps_snd_reports; /* sent membership reports */ }; NETSTATUS_ip - Internet protocol statistics The statistics data will be of the following format: struct ipstat { ULONG ips_total; /* total packets received */ ULONG ips_badsum; /* checksum bad */ ULONG ips_tooshort; /* packet too short */ ULONG ips_toosmall; /* not enough data */ ULONG ips_badhlen; /* ip header length < data size */ ULONG ips_badlen; /* ip length < ip header length */ ULONG ips_fragments; /* fragments received */ ULONG ips_fragdropped; /* frags dropped (dups, out of space) */ ULONG ips_fragtimeout; /* fragments timed out */ ULONG ips_forward; /* packets forwarded */ ULONG ips_cantforward; /* packets rcvd for unreachable dest */ ULONG ips_redirectsent; /* packets forwarded on same net */ ULONG ips_noproto; /* unknown or unsupported protocol */ ULONG ips_delivered; /* datagrams delivered to upper level*/ ULONG ips_localout; /* total ip packets generated here */ ULONG ips_odropped; /* lost packets due to nobufs, etc. */ ULONG ips_reassembled; /* total packets reassembled ok */ ULONG ips_fragmented; /* datagrams sucessfully fragmented */ ULONG ips_ofragments; /* output fragments created */ ULONG ips_cantfrag; /* don't fragment flag was set, etc. */ ULONG ips_badoptions; /* error in option processing */ ULONG ips_noroute; /* packets discarded due to no route */ ULONG ips_badvers; /* ip version != 4 */ ULONG ips_rawout; /* total raw ip packets generated */ }; NETSTATUS_mb - Memory buffer statistics The statistics data will be of the following format: struct mbstat { ULONG m_mbufs; /* mbufs obtained from page pool */ ULONG m_clusters; /* clusters obtained from page pool */ ULONG m_spare; /* spare field */ ULONG m_clfree; /* free clusters */ ULONG m_drops; /* times failed to find space */ ULONG m_wait; /* times waited for space */ ULONG m_drain; /* times drained protocols for space */ }; NETSTATUS_mrt - Multicast routing statistics The statistics data will be of the following format: struct mrtstat { ULONG mrts_mrt_lookups; /* # multicast route lookups */ ULONG mrts_mrt_misses; /* # multicast route cache misses */ ULONG mrts_grp_lookups; /* # group address lookups */ ULONG mrts_grp_misses; /* # group address cache misses */ ULONG mrts_no_route; /* no route for packet's origin */ ULONG mrts_bad_tunnel; /* malformed tunnel options */ ULONG mrts_cant_tunnel; /* no room for tunnel options */ ULONG mrts_wrong_if; /* arrived on the wrong interface */ }; NETSTATUS_rt - Routing statistics The statistics data will be of the following format: struct rtstat { WORD rts_badredirect; /* bogus redirect calls */ WORD rts_dynamic; /* routes created by redirects */ WORD rts_newgateway; /* routes modified by redirects */ WORD rts_unreach; /* lookups which failed */ WORD rts_wildcard; /* lookups satisfied by a wildcard */ }; NETSTATUS_tcp - Transmission control protocol statistics The statistics data will be of the following format: struct tcpstat { ULONG tcps_connattempt; /* connections initiated */ ULONG tcps_accepts; /* connections accepted */ ULONG tcps_connects; /* connections established */ ULONG tcps_drops; /* connections dropped */ ULONG tcps_conndrops; /* embryonic connections dropped */ ULONG tcps_closed; /* conn. closed (includes drops) */ ULONG tcps_segstimed; /* segs where we tried to get rtt */ ULONG tcps_rttupdated; /* times we succeeded */ ULONG tcps_delack; /* delayed acks sent */ ULONG tcps_timeoutdrop; /* conn. dropped in rxmt timeout */ ULONG tcps_rexmttimeo; /* retransmit timeouts */ ULONG tcps_persisttimeo; /* persist timeouts */ ULONG tcps_keeptimeo; /* keepalive timeouts */ ULONG tcps_keepprobe; /* keepalive probes sent */ ULONG tcps_keepdrops; /* connections dropped in keepalive */ ULONG tcps_sndtotal; /* total packets sent */ ULONG tcps_sndpack; /* data packets sent */ ULONG tcps_sndbyte; /* data bytes sent */ ULONG tcps_sndrexmitpack; /* data packets retransmitted */ ULONG tcps_sndrexmitbyte; /* data bytes retransmitted */ ULONG tcps_sndacks; /* ack-only packets sent */ ULONG tcps_sndprobe; /* window probes sent */ ULONG tcps_sndurg; /* packets sent with URG only */ ULONG tcps_sndwinup; /* window update-only packets sent */ ULONG tcps_sndctrl; /* control (SYN|FIN|RST) packets sent */ ULONG tcps_rcvtotal; /* total packets received */ ULONG tcps_rcvpack; /* packets received in sequence */ ULONG tcps_rcvbyte; /* bytes received in sequence */ ULONG tcps_rcvbadsum; /* packets received with ccksum errs */ ULONG tcps_rcvbadoff; /* packets received with bad offset */ ULONG tcps_rcvshort; /* packets received too short */ ULONG tcps_rcvduppack; /* duplicate-only packets received */ ULONG tcps_rcvdupbyte; /* duplicate-only bytes received */ ULONG tcps_rcvpartduppack; /* packets with some duplicate data */ ULONG tcps_rcvpartdupbyte; /* dup. bytes in part-dup. packets */ ULONG tcps_rcvoopack; /* out-of-order packets received */ ULONG tcps_rcvoobyte; /* out-of-order bytes received */ ULONG tcps_rcvpackafterwin; /* packets with data after window */ ULONG tcps_rcvbyteafterwin; /* bytes rcvd after window */ ULONG tcps_rcvafterclose; /* packets rcvd after "close" */ ULONG tcps_rcvwinprobe; /* rcvd window probe packets */ ULONG tcps_rcvdupack; /* rcvd duplicate acks */ ULONG tcps_rcvacktoomuch; /* rcvd acks for unsent data */ ULONG tcps_rcvackpack; /* rcvd ack packets */ ULONG tcps_rcvackbyte; /* bytes acked by rcvd acks */ ULONG tcps_rcvwinupd; /* rcvd window update packets */ ULONG tcps_pawsdrop; /* segments dropped due to PAWS */ ULONG tcps_predack; /* times hdr predict ok for acks */ ULONG tcps_preddat; /* times hdr predict ok for data pkts */ ULONG tcps_pcbcachemiss; ULONG tcps_persistdrop; /* timeout in persist state */ ULONG tcps_badsyn; /* bogus SYN, e.g. premature ACK */ }; NETSTATUS_udp - User datagram protocol statistics The statistics data will be of the following format: struct udpstat { /* input statistics: */ ULONG udps_ipackets; /* total input packets */ ULONG udps_hdrops; /* packet shorter than header */ ULONG udps_badsum; /* checksum error */ ULONG udps_badlen; /* data length larger than packet */ ULONG udps_noport; /* no socket on port */ ULONG udps_noportbcast; /* of above, arrived as broadcast */ ULONG udps_fullsock; /* not delivered, input socket full */ ULONG udpps_pcbcachemiss; /* input packets missing pcb cache */ /* output statistics: */ ULONG udps_opackets; /* total output packets */ }; NETSTATUS_tcp_sockets - Information on all TCP connections; the data will be in the following format (one such entry for each connection): struct protocol_connection_data { struct in_addr pcd_foreign_address; /* Foreign host address */ UWORD pcd_foreign_port; /* Foreign port number */ struct in_addr pcd_local_address; /* Local host address */ UWORD pcd_local_port; /* Local port number */ ULONG pcd_receive_queue_size; /* Socket receive queue size */ ULONG pcd_send_queue_size; /* Socket send queue size */ LONG pcd_tcp_state; /* Socket TCP state */ }; The 'pcd_tcp_state' member will contain the socket's TCP state, as defined in . Note that this can be -1 if the case cannot be safely determined. NETSTATUS_udp_sockets - Information on all UDP sockets; the data will be in the same format as with 'NETSTATUS_tcp_sockets'. However, the 'pcd_tcp_state' member of each entry will be -1 since that information is valid only for TCP. RESULT length -- Number of bytes copied, or -1 for failure. The failure code will be stored in the 'errno' variable. NOTES The GetNetworkStatistics() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_STATUS_API tag with the SocketBaseTagList() function. bsdsocket.library/getpeername bsdsocket.library/getpeername NAME getpeername - get name of connected peer SYNOPSIS success = getpeername(s, name,namelen) D0 D0 A0 A1 long getpeername(long s, struct sockaddr *name, long *namelen); FUNCTION getpeername() returns the name of the peer connected to socket s. The namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). The name is truncated if the buffer provided is too small. RESULT A 0 is returned if the call succeeds, -1 if it fails. ERRORS The call succeeds unless: [EBADF] The argument s is not a valid descriptor. [ENOTSOCK] The argument s is a file, not a socket. [ENOTCONN] The socket is not connected. [ENOBUFS] Insufficient resources were available in the system to perform the operation. [EFAULT] The name parameter points to memory not in a valid part of the process address space. SEE ALSO accept(), bind(), socket(), getsockname() bsdsocket.library/getprotobyname bsdsocket.library/getprotobyname NAME getprotobyname - get protocol entry SYNOPSIS #include protoent = getprotobyname(name) D0 A0 struct protoent * getprotobyname(char *name); FUNCTION The getprotobyname() and getprotobynumber() functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network protocol data base. struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ long p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero terminated list of alternate names for the protocol. p_proto The protocol number. The getprotobyname() function and getprotobynumber() sequentially search from the beginning of the file until a matching protocol name or protocol number is found, or until EOF is encountered. RESULT Null pointer (0) returned on EOF or error. BUGS These functions use a static data space; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet protocols are currently understood. bsdsocket.library/getprotobynumber bsdsocket.library/getprotobynumber NAME getprotobynumber - get protocol entry SYNOPSIS #include protoent = getprotobynumber(proto) D0 D0 struct protoent * getprotobynumber(long proto); FUNCTION The getprotobyname() and getprotobynumber() functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network protocol data base. struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ long p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero terminated list of alternate names for the protocol. p_proto The protocol number. The getprotobyname() function and getprotobynumber() sequentially search from the beginning of the file until a matching protocol name or protocol number is found, or until EOF is encountered. RESULT Null pointer (0) returned on EOF or error. BUGS These functions use a static data space; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet protocols are currently understood. bsdsocket.library/getprotoent bsdsocket.library/getprotoent NAME getprotoent - get protocol entry SYNOPSIS #include entry = getprotoent() D0 struct protoent * getprotoent(void); FUNCTION The getprotoent() function reads the next line of the protocol, database, opening the database file if necessary. RESULT Null pointer (0) returned on EOF or error. SEE ALSO endprotoent(), getprotobynumber(), getprotobyname(), setprotoent() BUGS These functions use a static data space; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet protocols are currently understood. NOTES The getprotoent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/GetRouteInfo bsdsocket.library/GetRouteInfo NAME GetRouteInfo - Obtain information on the routing tables. SYNOPSIS table = GetRouteInfo(address_family, flags) D0 D0 D1 struct rt_msghdr *GetRouteInfo(LONG address_family, LONG flags); FUNCTION This function will make a copy of the kernel's routing tables and return it to you for inspection. Each table entry takes the shape of a 'struct rt_msghdr'. INPUTS address_family -- The address family to obtain routing information for; this can be AF_UNSPEC or AF_INET. flags -- Flags which have to be set in each routing table entry to be returned (a combination of RTF_UP, RTF_GATEWAY, RTF_HOST, RTF_REJECT, RTF_DYNAMIC, RTF_MODIFIED, RTF_DONE, RTF_MASK, RTF_CLONING, RTF_XRESOLVE, RTF_LLINFO, RTF_STATIC or RTF_BLACKHOLE). A 'flags' value of 0 will cause the entire routing table to be returned. RESULT success -- a pointer to a copy of the routing table information or NULL for failure; the failure code will be stored in the 'errno' variable. Each table entry has the following format (see ): struct rt_msghdr { u_short rtm_msglen; u_char rtm_version; u_char rtm_type; u_short rtm_index; pid_t rtm_pid; int rtm_addrs; int rtm_seq; int rtm_errno; int rtm_flags; int rtm_use; u_long rtm_inits; struct rt_metrics rtm_rmx; }; The table is terminated by a dummy entry whose 'rtm_msglen' member is zero. NOTES The GetRouteInfo() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ROUTING_API tag with the SocketBaseTagList() function. The format and layout of the data to be returned may change. Check the 'rtm_version' member of each table entry to verify that your code is really referring to the expected information. The 'struct rt_msghdr' layout described above corresponds to version 3. SEE ALSO FreeRouteInfo(), route bsdsocket.library/getservbyname bsdsocket.library/getservbyname NAME getservbyname - get service entry SYNOPSIS #include servent = getservbyname(name, proto) D0 A0 A1 struct servent * getservbyname(char *name, char *proto); FUNCTION The getservbyname() and getservbyport() functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network services data base. struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ long s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero terminated list of alternate names for the service. s_port The port number at which the service resides. Port numbers are returned in network byte order. s_proto The name of the protocol to use when contacting the service. The getservbyname() and getservbyport() functions sequentially search from the beginning of the file until a matching protocol name or port number is found, or until EOF is encountered. If a protocol name is also supplied (non-NULL), searches must also match the protocol. RESULT Null pointer (0) returned on EOF or error. SEE ALSO getservent(), setservent(), endservent() BUGS These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Expecting port numbers to fit in a 32 bit quantity is probably naive. bsdsocket.library/getservbyport bsdsocket.library/getservbyport NAME getservbyport - get service entry SYNOPSIS #include servent = getservbyport(port, proto) D0 D0 A0 struct servent * getservbyport(long port, char *proto); FUNCTION The getservbyname() and getservbyport() functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network services data base. struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ long s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero terminated list of alternate names for the service. s_port The port number at which the service resides. Port numbers are returned in network byte order. s_proto The name of the protocol to use when contacting the service. The getservbyname() and getservbyport() functions sequentially search from the beginning of the file until a matching protocol name or port number is found, or until EOF is encountered. If a protocol name is also supplied (non-NULL), searches must also match the protocol. RESULT Null pointer (0) returned on EOF or error. BUGS These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Expecting port numbers to fit in a 32 bit quantity is probably naive. bsdsocket.library/getservent bsdsocket.library/getservent NAME getservent - get service entry SYNOPSIS #include entry = getservent() D0 struct servent * getservent(void); FUNCTION The getservent() function reads the next line of the service database, opening the database if necessary. RESULT Null pointer (0) returned on EOF or error. SEE ALSO setservent(), getservbyname(), getservbyport(), endservent() BUGS These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Expecting port numbers to fit in a 32 bit quantity is probably naive. NOTES The getservent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/GetSocketEvents bsdsocket.library/GetSocketEvents NAME GetSocketEvents - get the next asynchronous event triggered by socket I/O [AmiTCP V4] SYNOPSIS socket = GetSocketEvents(events_ptr) D0 A0 long GetSocketEvents(ULONG * events_ptr); FUNCTION GetSocketEvents() returns the next asynchronous event for sockets, and removes it from the internal queue. The socket number for which the event has occured is returned. If no asynchronous event is pending then -1 is returned. Applications are notified of asynchronous events through the event signal (which has to be set earlier by calling SocketBaseTags() with the SBTC_SIGEVENTMASK tag). Several different events can occur for each socket. To enable reporting of specific events for a socket call setsockopt() with the option SO_EVENTMASK. After calling GetSocketEvents() the ULONG pointed to by events_ptr contains the mask of all events that have occured for the returned socket. Possible events include: FD_ACCEPT A new connection is waiting to be accepted. The kernel keeps track of each pending connection. If more than one connection is pending then the kernel immediately generates a new FD_ACCEPT event until all pending connections are accounted for. FD_CLOSE The connection was closed. If it was closed due to an error then the FD_ERROR event is set as well. FD_CONNECT A pending connection has been established. This event is an indication that a non-blocking connect() has been completed. FD_ERROR An asynchronous error has occured. When this event is found, the 'errno' variable will be set to the error code associated with the socket which triggered the error event. The error code associated with the socket is not cleared. Use the getsockopt(socket,SO_ERROR,..) function to do that, which will read and clear the error code. FD_OOB New out-of-band data is available for reading. FD_READ New data is available for reading. FD_WRITE The socket is able to accept data for writing again without blocking (only for non-blocking sockets). RESULT The value -1 is returned if no asynchronous events are pending. Otherwise, a socket descriptor number will be returned. SEE ALSO setsockopt(), getsockopt() bsdsocket.library/getsockname bsdsocket.library/getsockname NAME getsockname - get socket name SYNOPSIS success = getsockname(s, name, namelen) D0 D0 A0 A1 long getsockname(long s, struct sockaddr *name, long *namelen); FUNCTION getsockname() returns the current name for the specified socket. The namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). RESULT A 0 is returned if the call succeeds, -1 if it fails. ERRORS The call succeeds unless: [EBADF] The argument s is not a valid descriptor. [ENOTSOCK] The argument s is not a socket. [ENOBUFS] Insufficient resources were available in the system to perform the operation. [EFAULT] The name parameter points to memory not in a valid part of the process address space. SEE ALSO bind(), socket() bsdsocket.library/getsockopt bsdsocket.library/getsockopt NAME getsockopt - get options on sockets SYNOPSIS #include #include success = getsockopt(s, level, optname, optval, optlen) D0 D0 D1 D2 A0 A1 long getsockopt(long s, long level, long optname, void *optval, long *optlen); FUNCTION getsockopt() and setsockopt() manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost ``socket'' level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP. The parameters optval and optlen are used to access option values for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, optval may be NULL. Optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. Most socket-level options utilize an int parameter for optval. For setsockopt(), the parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. SO_LINGER uses a struct linger parameter, defined in , which specifies the desired state of the option and the linger interval (see below). SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parameter, defined in . The following options are recognized at the socket level. Except as noted, each may be examined with getsockopt() and set with setsockopt(). SO_DEBUG enables recording of debugging information SO_REUSEADDR enables local address reuse SO_REUSEPORT enables duplicate address and port bindings SO_KEEPALIVE enables keep connections alive SO_DONTROUTE enables routing bypass for outgoing messages SO_LINGER linger on close if data present SO_BROADCAST enables permission to transmit broadcast messages SO_OOBINLINE enables reception of out-of-band data in band SO_SNDBUF set buffer size for output SO_RCVBUF set buffer size for input SO_SNDLOWAT set minimum count for output SO_RCVLOWAT set minimum count for input SO_SNDTIMEO set timeout value for output SO_RCVTIMEO set timeout value for input SO_TYPE get the type of the socket (get only) SO_ERROR get and clear error on the socket (get only) SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind() call should allow reuse of local addresses. SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. SO_LINGER controls the action taken when unsent messages are queued on socket and a CloseSocket() is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in seconds in the setsockopt() call when SO_LINGER is requested). If SO_LINGER is disabled and a close is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The option SO_BROADCAST requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv or read calls without the MSG_OOB flag. Some protocols always behave as if this option is set. SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. SO_SNDLOWAT is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A WaitSelect() operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for SO_SNDLOWAT is set to a convenient size for network efficiency, often 1024. SO_RCVLOWAT is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with the smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error EWOULDBLOCK if no data were sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error EWOULDBLOCK if no data were received. Finally, SO_TYPE and SO_ERROR are options used only with getsockopt(). SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful for servers that inherit sockets on startup. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. RESULT A 0 is returned if the call succeeds, -1 if it fails. ERRORS The call succeeds unless: [EBADF] The argument s is not a valid descriptor. [ENOTSOCK] The argument s is a file, not a socket. [ENOPROTOOPT] The option is unknown at the level indicated. [EFAULT] The address pointed to by optval is not in a valid part of the process address space. For getsockopt(), this error may also be returned if optlen is not in a valid part of the process address space. SEE ALSO IoctlSocket(), socket() bsdsocket.library/In_CanForward bsdsocket.library/In_CanForward NAME In_CanForward - Determine whether an IP address is in a reserved set of addresses that may not be forwarded, or whether datagrams to that destination may be forwarded. SYNOPSIS #include result = In_CanForward(address) D0 D0 LONG In_CanForward(ULONG address); FUNCTION The In_CanForward() routine will check if an IP address is in a reserved set of addresses that may not be forwarded, or whether datagrams to that destination may be forwarded. This should not be confused with the set of addresses reserved for use in private internets (as described in RFC1918). INPUTS address -- The internet address to be tested. RESULT Returns 1 if datagrams may be forwarded to the address and 0 otherwise. NOTES The In_CanForward() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ADDRESS_CONVERSION_API tag with the SocketBaseTagList() function. bsdsocket.library/In_LocalAddr bsdsocket.library/In_LocalAddr NAME In_LocalAddr - Check if an internet address is for a 'local' host. SYNOPSIS #include result = In_LocalAddr(address) D0 D0 LONG In_LocalAddr(ULONG address); FUNCTION The In_LocalAddr() routine will check if an internet address is for a 'local' host (one to which we have a connection). INPUTS address -- The internet address to be tested. RESULT Returns 1 if the address was for a local host and 0 otherwise. NOTES The In_LocalAddr() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ADDRESS_CONVERSION_API tag with the SocketBaseTagList() function. bsdsocket.library/inet_addr bsdsocket.library/inet_addr NAME inet_addr - Internet address manipulation SYNOPSIS #include #include #include addr = inet_addr(cp) D0 A0 unsigned long inet_addr(char *cp); FUNCTION The routines inet_aton(), inet_addr() and inet_network() interpret character strings representing numbers expressed in the Internet standard `.' notation. The inet_aton() routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The inet_addr() and inet_network() functions return numbers suitable for use as Internet addresses and Internet net work numbers, respectively. The routine Inet_NtoA() takes an Internet address and returns an ASCII string representing the address in `.' notation. The routine inet_makeaddr() takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof() and inet_lnaof() break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RESULT The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. SEE ALSO gethostbyname() BUGS The value INADDR_NONE (0xffffffff) is a valid broadcast address, but inet_addr() cannot return that value without indicating failure. The newer inet_aton() function does not share this problem. The problem of host byte ordering versus network byte ordering is confusing. The string returned by Inet_NtoA() resides in a static memory area. bsdsocket.library/inet_aton bsdsocket.library/inet_aton NAME inet_aton - Internet address manipulation SYNOPSIS #include #include #include valid = inet_aton(cp,addr) D0 A0 A1 long inet_aton(char *cp,struct in_addr *addr); FUNCTION The routines inet_aton(), inet_addr() and inet_network() interpret character strings representing numbers expressed in the Internet standard `.' notation. The inet_aton() routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RESULT Returns 1 if the IP address was valid, and initializes the address pointed to by the second parameter, or 0 for an invalid IP address. SEE ALSO gethostbyname(), inet_addr() NOTES The inet_aton() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ADDRESS_CONVERSION_API tag with the SocketBaseTagList() function. bsdsocket.library/Inet_LnaOf bsdsocket.library/Inet_LnaOf NAME Inet_LnaOf - Internet address manipulation SYNOPSIS #include #include #include lna = Inet_LnaOf(in) D0 D0 unsigned long Inet_LnaOf(unsigned long in); FUNCTION The routines inet_aton(), inet_addr() and inet_network() interpret character strings representing numbers expressed in the Internet standard `.' notation. The inet_aton() routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The inet_addr() and inet_network() functions return numbers suitable for use as Internet addresses and Internet net work numbers, respectively. The routine Inet_NtoA() takes an Internet address and returns an ASCII string representing the address in `.' notation. The routine inet_makeaddr() takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof() and inet_lnaof() break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. NOTES Inet_LnaOf() corresponds to inet_lnaof(), which accepts a 'struct in_addr' parameter. Effectively, only the in_addr.s_addr member is used by that library function, which is what the Inet_Lnaof() function uses as a parameter. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RESULT The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. SEE ALSO gethostbyname() NOTES This function predates a change in the Internet architecture known as "Classless Internet Domain Routing" (CIDR). Following this change it is no longer safe to determine the local network address part of an IP address merely by checking the type of the address. BUGS The value INADDR_NONE (0xffffffff) is a valid broadcast address, but inet_addr() cannot return that value without indicating failure. The newer inet_aton() function does not share this problem. The problem of host byte ordering versus network byte ordering is confusing. The string returned by Inet_NtoA() resides in a static memory area. bsdsocket.library/Inet_MakeAddr bsdsocket.library/Inet_MakeAddr NAME Inet_MakeAddr - Internet address manipulation SYNOPSIS #include #include #include in_addr = Inet_MakeAddr(net, lna) D0 D0 D1 unsigned long Inet_MakeAddr(long net, long lna); FUNCTION The routines inet_aton(), inet_addr() and inet_network() interpret char acter strings representing numbers expressed in the Internet standard `.' notation. The inet_aton() routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The inet_addr() and inet_network() functions return numbers suitable for use as Internet addresses and Internet net work numbers, respectively. The routine Inet_NtoA() takes an Internet address and returns an ASCII string representing the address in `.' notation. The routine inet_makeaddr() takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof() and inet_lnaof() break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. NOTES Inet_MakeAddr() corresponds to inet_makeaddr(), which returns a 'struct in_addr' value. Effectively, only the in_addr.s_addr member is filled in which is what the inet_makeaddr() function returns as its result. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RESULT The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. SEE ALSO gethostbyname() BUGS The value INADDR_NONE (0xffffffff) is a valid broadcast address, but inet_addr() cannot return that value without indicating failure. The newer inet_aton() function does not share this problem. The problem of host byte ordering versus network byte ordering is confusing. The string returned by Inet_NtoA() resides in a static memory area. bsdsocket.library/Inet_NetOf bsdsocket.library/Inet_NetOf NAME Inet_NetOf - Internet address manipulation SYNOPSIS #include #include #include net = Inet_NetOf(in) D0 D0 unsigned long Inet_NetOf(unsigned long in); FUNCTION The routines inet_aton(), inet_addr() and inet_network() interpret character strings representing numbers expressed in the Internet standard `.' notation. The inet_aton() routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The inet_addr() and inet_network() functions return numbers suitable for use as Internet addresses and Internet net work numbers, respectively. The routine Inet_NtoA() takes an Internet address and returns an ASCII string representing the address in `.' notation. The routine inet_makeaddr() takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof() and inet_lnaof() break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. NOTES Inet_NetOf() corresponds to inet_netof(), which accepts a 'struct in_addr' parameter. Effectively, only the in_addr.s_addr member is used by that library function, which is what the Inet_Netof() function uses as a parameter. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RESULT The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. SEE ALSO gethostbyname() NOTES This function predates a change in the Internet architecture known as "Classless Internet Domain Routing" (CIDR). Following this change it is no longer safe to determine the local network number part of an IP address merely by checking the type of the address. BUGS The value INADDR_NONE (0xffffffff) is a valid broadcast address, but inet_addr() cannot return that value without indicating failure. The newer inet_aton() function does not share this problem. The problem of host byte ordering versus network byte ordering is confusing. The string returned by Inet_NtoA() resides in a static memory area. bsdsocket.library/inet_network bsdsocket.library/inet_network NAME inet_network - Internet address manipulation SYNOPSIS #include #include #include net = inet_network(cp) D0 A0 unsigned long inet_network(char *cp); FUNCTION The routines inet_aton(), inet_addr() and inet_network() interpret char acter strings representing numbers expressed in the Internet standard `.' notation. The inet_aton() routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The inet_addr() and inet_network() functions return numbers suitable for use as Internet addresses and Internet net work numbers, respectively. The routine Inet_NtoA() takes an Internet address and returns an ASCII string representing the address in `.' notation. The routine inet_makeaddr() takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof() and inet_lnaof() break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RESULT The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. SEE ALSO gethostbyname() BUGS The value INADDR_NONE (0xffffffff) is a valid broadcast address, but inet_addr() cannot return that value without indicating failure. The newer inet_aton() function does not share this problem. The problem of host byte ordering versus network byte ordering is confusing. The string returned by Inet_NtoA() resides in a static memory area. bsdsocket.library/Inet_NtoA bsdsocket.library/Inet_NtoA NAME Inet_NtoA - Internet address manipulation SYNOPSIS #include #include #include addr = Inet_NtoA(in) D0 D0 char * Inet_NtoA(unsigned long in); FUNCTION The routines inet_aton(), inet_addr() and inet_network() interpret char acter strings representing numbers expressed in the Internet standard `.' notation. The inet_aton() routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The inet_addr() and inet_network() functions return numbers suitable for use as Internet addresses and Internet net work numbers, respectively. The routine inet_ntoa() takes an Internet address and returns an ASCII string representing the address in `.' notation. The routine inet_makeaddr() takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof() and inet_lnaof() break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. NOTES Inet_NtoA() corresponds to inet_ntoa(), which accepts a 'struct in_addr' parameter. Effectively, only the in_addr.s_addr member is used by that library function, which is what the Inet_NtoA() function uses as a parameter. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RESULT The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. SEE ALSO gethostbyname() BUGS The string returned by Inet_NtoA() resides in a static memory area. bsdsocket.library/inet_ntop bsdsocket.library/inet_ntop NAME inet_ntop - convert a network format address to presentation format. SYNOPSIS #include #include #include success = inet_ntop(af,src,dst,size) D0 D0 A0 A1 D1 STRPTR inet_ntop(LONG af,APTR src,STRPTR dst,LONG size); FUNCTION The inet_ntop() routine will convert a network address into an ASCII text representation. This is similar to inet_ntoa(), except that the output buffer is user-supplied and not statically allocated somewhere. INPUTS af -- Address family that identifies the encoding of the 'src' parameter; this must be AF_INET for IPv4 addresses. src -- Pointer to a network address, encoded in the form indicated by the 'af' parameter. dst -- Buffer to store the ASCII text representation in. This buffer must contain at least as many bytes of room as indicated by the 'size' parameter. size -- Size of the buffer pointed to by 'dst'. RESULT This routine returns the value of the 'dst' parameter, or NULL for failure. SEE ALSO gethostbyname(), inet_addr(), inet_ntoa(), inet_pton() NOTES The inet_ntop() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ADDRESS_CONVERSION_API tag with the SocketBaseTagList() function. bsdsocket.library/inet_pton bsdsocket.library/inet_pton NAME inet_pton - Convert a presentation format address to network format. SYNOPSIS #include #include #include result = inet_pton(af,src,dst) D0 D0 A0 A1 LONG inet_pton(LONG af,STRPTR src,APTR dst); FUNCTION The inet_pton() routine will convert an ASCII text representation of an IP address to network format, depending upon the type of address given. This is similar to inet_aton(). INPUTS af -- Address family that identifies the encoding of the 'src' parameter; this must be AF_INET for IPv4 addresses. src -- Pointer to the presentation format address, in the format indicated by the 'af' parameter. For IPv4 addresses, 'src' must point to a dotted-decimal representation of an IP address. That representation must be of the 'a.b.c.d' form, with 'a', 'b', 'c' and 'd', being numbers in the range 0..255 (inclusive). dst -- Buffer to store the network format address in. RESULT Returns 1 if the address was valid for the specified address family, 0 if the address was not valid ('dst' will not be modified in this case) and -1 if any other error occured ('dst' will not be modified in this case either). SEE ALSO gethostbyname(), inet_addr(), inet_ntoa(), inet_ntop() NOTES The inet_pton() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ADDRESS_CONVERSION_API tag with the SocketBaseTagList() function. bsdsocket.library/IoctlSocket bsdsocket.library/IoctlSocket NAME IoctlSocket - control socket parameters SYNOPSIS #include success = IoctlSocket(s, request, argp) D0 D0 D1 A0 long IoctlSocket(long s, unsigned long request, char *argp); FUNCTION The IoctlSocket() function manipulates the underlying device parameters of special files. The argument s must be a socket file descriptor. An ioctl request has encoded in it whether the argument is an ``in'' parameter or ``out'' parameter, and the size of the argument argp in bytes. Macros and defines used in specifying an ioctl request are located in the file . The following request types are supported: FIONBIO The argument must be (long *). A value of 1 enables non-blocking I/O on the socket, a value of 0 disables it. FIOASYNC The argument must be (long *). A value of 1 enables asynchronous I/O on the socket, a value of 0 disables it. FIONREAD The argument must be (long *). The number of characters readable on this socket will be returned. SIOCATMARK The argument must be (long *). If the socket points to a mark in the data stream then the value pointed to by the argument will be set to 1; otherwise it will be set to 0. NOTES Depending on the type of socket involved, other ioctl requests are supported, too. The table above only refers to the request types supported by the kernel code itself. RESULT If an error has occurred, a value of -1 is returned and errno is set to indicate the error. ERRORS IoctlSocket() will fail if: [EBADF] s is not a valid descriptor. [ENOTTY] s is not associated with a character special device. [ENOTTY] The specified request does not apply to the kind of object that the descriptor s references. [EINVAL] Request or argp is not valid. bsdsocket.library/listen bsdsocket.library/listen NAME listen - listen for connections on a socket SYNOPSIS #include success = listen(s, backlog) D0 D0 D1 long listen(long s, long backlog); FUNCTION To accept connections, a socket is first created with socket(), a willingness to accept incoming connections and a queue limit for incoming connections are specified with listen(), and then the connections are accepted with accept(). The listen() call applies only to sockets of type SOCK_STREAM or SOCK_SEQPACKET. The backlog parameter defines the maximum length the queue of pending connections may grow to. If a connection request arrives with the queue full the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. RESULT A 0 return value indicates success; -1 indicates an error. ERRORS listen() will fail if: [EBADF] The argument s is not a valid descriptor. [ENOTSOCK] The argument s is not a socket. [EOPNOTSUPP] The socket is not of a type that supports the operation listen(). SEE ALSO accept(), connect(), socket() BUGS The backlog is currently limited (silently) to 5. bsdsocket.library/mbuf_adj bsdsocket.library/mbuf_adj NAME mbuf_adj - Remove bytes from an mbuf chain. SYNOPSIS #include success = mbuf_adj(buffer,length) D0 A0 D0 LONG mbuf_adj(struct mbuf *buffer,LONG length); FUNCTION This function will remove bytes either from the beginning or the end of the mbuf chain. INPUTS buffer -- The mbuf chain to be modified; this must not be NULL. length -- Number of bytes to remove; if this is a positive value, the bytes will be removed from the beginning of the chain, otherwise they will be removed from the end of the chain. RESULT A success code is returned (0 == success, anything else indicates an error); this function will always succeed provided that the parameters are sane. NOTES The mbuf_adj() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_adj() is functionally identical to the BSD kernel routine "m_adj()". bsdsocket.library/mbuf_cat bsdsocket.library/mbuf_cat NAME mbuf_cat - Concatenate two mbuf chains. SYNOPSIS #include success = mbuf_cat(first_chain,second_chain) D0 A0 A1 LONG mbuf_cat(struct mbuf *first_chain,struct mbuf *second_chain); FUNCTION This function will concatenate the contents of one mbuf chain to another. INPUTS first_chain -- The mbuf chain the second chain will be appended to; this must not be NULL. second_chain -- The mbuf chain to be appended to the first chain; this must not be NULL. This buffer will be released after it has been copied. RESULT A success code is returned (0 == success, anything else indicates an error); this function will always succeed provided that the parameters are sane. NOTES The mbuf_cat() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_cat() is functionally identical to the BSD kernel routine "m_cat()". The 'first_chain->m_pkthdr' field will not be updated. The 'second_chain' buffer is destroyed by this function. bsdsocket.library/mbuf_copyback bsdsocket.library/mbuf_copyback NAME mbuf_copyback - Copy data from a buffer back into an mbuf chain. SYNOPSIS #include success = mbuf_copyback(buffer,offset,length,data) D0 A0 D0 D1 A1 LONG mbuf_copyback(struct mbuf *buffer,LONG offset, LONG length,APTR data); FUNCTION Copy data from a buffer back into the indicated mbuf chain, starting "offset" bytes from the beginning, extending the mbuf chain if necessary. INPUTS buffer -- The mbuf chain to be modified; this must not be NULL. offset -- How many bytes into the buffer contents the data should be copied; must be >= 0. length -- How many bytes should be copied; must be >= 0. data -- Refers to the data to be copied; this must not be NULL. RESULT A success code is returned (0 == success, anything else indicates an error). This function can fail if it runs out of memory whilst trying to extend the mbuf chain. NOTES The mbuf_copyback() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_copyback() is functionally identical to the BSD kernel routine "m_copyback()". bsdsocket.library/mbuf_copydata bsdsocket.library/mbuf_copydata NAME mbuf_copydata - Copy data from an mbuf chain into a buffer. SYNOPSIS #include success = mbuf_copydata(buffer,offset,length,data) D0 A0 D0 D1 A1 LONG mbuf_copydata(struct mbuf *buffer,LONG offset,LONG length, APTR data); FUNCTION Copy data from an mbuf chain starting "offset" bytes from the beginning, continuing for "length" bytes, into the indicated buffer. INPUTS buffer -- The mbuf chain to be copied; this must not be NULL. offset -- How many bytes into the buffer contents the data should be copied; must be >= 0. length -- How many bytes should be copied; must be >= 0. data -- Where the bytes should be copied to; this must not be NULL. RESULT A success code is returned (0 == success, anything else indicates an error). NOTES The mbuf_copydata() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_copydata() is functionally identical to the BSD kernel routine "m_copydata()". bsdsocket.library/mbuf_copym bsdsocket.library/mbuf_copym NAME mbuf_copym - Make a copy of an mbuf chain. SYNOPSIS #include copy = mbuf_copym(buffer,offset,length) D0 A0 D0 D1 struct mbuf * mbuf_copym(struct mbuf *buffer,LONG offset,LONG length); FUNCTION Make a copy of an mbuf chain starting "offset" bytes from the beginning, continuing for "length" bytes. If length==M_COPYALL, copy to end of mbuf. INPUTS buffer -- The mbuf chain to be copied. offset -- How many bytes into the buffer contents the data should be copied; must be >= 0. length -- How many bytes should be copied; must be >= 0. RESULT A copy of the original buffer is returned, taking the offset and length into account. If the copy could not be created, NULL is returned. NOTES The mbuf_copym() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_copym() is functionally identical to the BSD kernel routine "m_copym()". bsdsocket.library/mbuf_free bsdsocket.library/mbuf_free NAME mbuf_free - Free a single mbuf and return a pointer to the next mbuf in the chain. SYNOPSIS #include next = mbuf_free(buffer) D0 A0 struct mbuf * mbuf_free(struct mbuf *buffer); FUNCTION Free a single mbuf, as pointed to by the 'buffer' parameter. If the 'buffer' parameter refers to a cluster, then the memory will not be freed immediately, but rather when the usage count of the cluster drops to zero. If the mbuf is part of a chain, then the next following chain member will be returned. INPUTS buffer -- The mbuf to be freed; this can be NULL in which case this function will do nothing. RESULT A pointer to the next mbuf in the chain the 'buffer' parameter is a part of will be returned. If there is no such next mbuf, NULL will be returned instead. NOTES The mbuf_free() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_free() is functionally identical to the BSD kernel routine "m_free()". bsdsocket.library/mbuf_freem bsdsocket.library/mbuf_freem NAME mbuf_freem - Free all mbufs in a chain. SYNOPSIS #include mbuf_freem(chain) A0 VOID mbuf_freem(struct mbuf *chain); FUNCTION Free all mbufs in a chain. INPUTS buffer -- The mbuf chain to be freed; this can be NULL in which case this function will do nothing. NOTES The mbuf_freem() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_freem() is functionally identical to the BSD kernel routine "m_freem()". bsdsocket.library/mbuf_get bsdsocket.library/mbuf_get NAME mbuf_get - Allocate memory for an mbuf and initialize it. SYNOPSIS #include buffer = mbuf_get() D0 struct mbuf * mbuf_get(VOID); FUNCTION Allocate memory for a single mbuf and initialize it. RESULT A pointer to the allocated mbuf will be returned, or NULL if there was not enough memory available to allocate it. NOTES The mbuf_get() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_get() is functionally identical to the BSD kernel routine "m_get()". bsdsocket.library/mbuf_gethdr bsdsocket.library/mbuf_gethdr NAME mbuf_gethdr - Allocate memory for a single mbuf and initialize it as a packet header. SYNOPSIS #include buffer = mbuf_gethdr() D0 struct mbuf * mbuf_gethdr(VOID); FUNCTION Allocate memory for a single mbuf and initialize it as a packet header. RESULT A pointer to the allocated mbuf will be returned, or NULL if there was not enough memory available to allocate it. NOTES The mbuf_gethdr() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_gethdr() is functionally identical to the BSD kernel routine "m_gethdr()". bsdsocket.library/mbuf_prepend bsdsocket.library/mbuf_prepend NAME mbuf_prepend - Allocate new mbuf to be prepended to chain. SYNOPSIS #include new_buffer = mbuf_prepend(buffer,length) D0 A0 D0 LONG mbuf_prepend(struct mbuf *buffer,LONG length); FUNCTION This function allocates a new mbuf which will be prepended to the mbuf chain provided; if the new mbuf cannot be allocated, then the provided mbuf chain will be deallocated. INPUTS buffer -- The mbuf chain a new mbuf is to be prepended to; this must not be NULL. length -- How many bytes to prepend; must be >= 0. RESULT Returns the new mbuf chain with the new buffer prepended, or NULL if memory was short; in case of failure, the original memory buffer chain will be deallocated. NOTES The mbuf_prepend() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_prepend() is functionally identical to the BSD kernel routine "m_prepend()". bsdsocket.library/mbuf_pullup bsdsocket.library/mbuf_pullup NAME mbuf_pullup - Rearrange an mbuf chain so that len bytes are contiguous and in the data area of an mbuf. SYNOPSIS #include new_buffer = mbuf_pullup(buffer,length) D0 A0 D0 struct mbuf * mbuf_pullup(struct mbuf *buffer,LONG length); FUNCTION Rearrange an mbuf chain so that len bytes are contiguous and in the data area of an mbuf (so that mtod() and dtom() macros will work for a structure of size 'length'). Returns the resulting mbuf chain on success. If there is room, it will add up to max_protohdr-len extra bytes to the contiguous region in an attempt to avoid being called next time. INPUTS buffer -- The mbuf chain to be rearranged. length -- How many bytes should be stored contiguously in the first mbuf of the chain. RESULT This function returns the rearranged mbuf chain on success. If there was not enough memory available, NULL will be returned instead. NOTES The mbuf_pullup() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_KERNEL_MEMORY_API tag with the SocketBaseTagList() function. This routine is expected to be called on the context of the kernel from within the IP filter hook. Do not call it from user code or you will crash the stack. mbuf_pullup() is functionally identical to the BSD kernel routine "m_pullup()". bsdsocket.library/ObtainDomainNameServerListibrary/ObtainDomainNameServerList NAME ObtainDomainNameServerList - Obtain the local in-memory list of domain name server addresses used by the resolver. SYNOPSIS list = ObtainDomainNameServerList() D0 struct List * ObtainDomainNameServerList(void); FUNCTION The ObtainDomainNameServerList() function will make a copy of the current list of local domain name server addresses, as used by the resolver. A list will be returned and must be released later via the ReleaseDomainNameServerList() function. RESULT list -- Pointer to a 'struct List', whose individual nodes contain the addresses. Each node contains the following structure members: dnsn_MinNode A regular 'struct MinNode' which introduces each list entry. dnsn_Size The size of this data structure in bytes. Future versions of this library may offer additional members; by comparing the size you can find out whether this is the case. dnsn_Address The address of a domain name server, expressed as a NUL-terminated string in dotted-decimal notation (per RFC1700). dnsn_UseCount How many times this server address has been added to the list so far. A negative value indicates that this server was configured statically in the 'DEVS:Internet/resolver' file. The result can be NULL if there was not enough memory available to fill it. If no local name server addresses have been added yet, you will receive an empty list. NOTES The ObtainDomainNameServerList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_DNS_API tag with the SocketBaseTagList() function. SEE ALSO ReleaseDomainNameServerList() bsdsocket.library/ObtainInterfaceList bsdsocket.library/ObtainInterfaceList NAME ObtainInterfaceList - Obtain a list of available interfaces SYNOPSIS list = ObtainInterfaceList() D0 struct List * ObtainInterfaceList(void); FUNCTION The ObtainInterfaceList() function will make a copy of the current list of interfaces, as available for use by the stack. This list will be returned and must be released later via the ReleaseInterfaceList() function. RESULT list -- Pointer to a 'struct List', whose individual Nodes contain the names of the respective interfaces (found in node->ln_Name). The result can be NULL if there was not enough memory available to fill it. If no interfaces have been added yet, you will receive an empty list. NOTES The ObtainInterfaceList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. SEE ALSO ReleaseInterfaceList() bsdsocket.library/ObtainRoadshowData bsdsocket.library/ObtainRoadshowData NAME ObtainRoadshowData - Access internal Roadshow configuration data SYNOPSIS list = ObtainRoadshowData(access) D0 D0 struct List *ObtainRoadshowData(LONG access); FUNCTION Several internal options control how the TCP/IP stack works. These do not normally need to be changed, but there are times when you might want to override or check them. ObtainRoadshowData() gives you access to the list of known configurable options. INPUTS access -- This must be one of the following values: ORD_ReadAccess You just want to examine the options. ORD_WriteAccess You want to modify and possibly examine the options. RESULT list -- Pointer to a list, or NULL in case of error. Note that the list and its contents are read-only! The list items look as follows: struct RoadshowDataNode { struct MinNode rdn_MinNode; STRPTR rdn_Name; UWORD rdn_Flags; WORD rdn_Type; ULONG rdn_Length; APTR rdn_Data; }; The structure members serve the following purposes: rdn_MinNode This is a standard list node link. rdn_Name Points to the NUL-terminated name of the option. rdn_Flags This node may have special properties, such as: RDNF_ReadOnly If this flag is set, it means that you can examine the option, but it cannot be modified with the ChangeRoadshowData() function. rdn_Type The type of data this option represents, such as: RDNT_Integer This is a signed 32 bit integer. rdn_Length This holds the size of the data associated with this option, given as the number of bytes allocated for it. rdn_Data Points to the data associated with this option. ERRORS The ObtainRoadshowData() call fails if: [EINVAL] The list access mode is neither ORD_ReadAccess nor ORD_WriteAccess. NOTES The ObtainRoadshowData() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ROADSHOWDATA_API tag with the SocketBaseTagList() function. Only one caller can modify the options at a time. SEE ALSO ReleaseRoadshowData(), ChangeRoadshowData() bsdsocket.library/ObtainServerSocket bsdsocket.library/ObtainServerSocket NAME ObtainServerSocket - Claim the socket associated with the current Process' Internet server connection. SYNOPSIS socket = ObtainServerSocket() D0 LONG ObtainServerSocket(VOID); FUNCTION Programs can be launched by the Internet superserver. These programs will have sockets associated with them, connected to a client on the network. A program can call ObtainServerSocket() to claim this socket. RESULT socket -- The socket assigned to this server program, or -1 if no such socket is assigned or was already claimed. NOTES The ObtainServerSocket() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_SERVER_API tag with the SocketBaseTagList() function. SEE ALSO ObtainSocket() ProcessIsServer() bsdsocket.library/ObtainSocket bsdsocket.library/ObtainSocket NAME ObtainSocket - acquire a socket from the public list SYNOPSIS socket = ObtainSocket(id, domain, type, protocol) D0 D0 D1 D2 D3 long ObtainSocket(long id, long domain, long type, long protocol); FUNCTION This function is for passing control of a socket from one process to another. The socket to be handed over must be identified by an ID, a domain, type and protocol number. RESULT A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. ERRORS The ObtainSocket() call fails if: [EBADF] No socket with the given Id could be found. [EPROTONOSUPPORT] The protocol type or the specified protocol is not supported within this domain. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [EACCESS] Permission to create a socket of the specified type and/or protocol is denied. [ENOBUFS] Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed. SEE ALSO socket(), accept(), bind(), connect(), getsockname(), getsockopt(), IoctlSocket(), listen(), recv(), WaitSelect(), send(), shutdown(), ReleaseSocket() bsdsocket.library/OpenLibrary bsdsocket.library/OpenLibrary NAME OpenLibrary -- Open "bsdsocket.library", binding the opening Process to the library base returned. SYNOPSIS #include Library = OpenLibrary(Name,Version) D0 A1 D0 struct Library * OpenLibrary(STRPTR name,ULONG version); FUNCTION Each time "bsdsocket.library" is opened, a pointer to a specially crafted library base will be returned to the opener. This library base must be considered private in that it was created for the opener's use only. It is unwise to share this library base with other Processes since, for example, signals will be delivered only to the opener but not to the Process which shares the library base with the opener. This can be an issue for features such as interface address change notification, asynchronous I/O, out of band data or event notification. These signals will be posted only for the library opener. The recommended approach, if several Processes need to use the "bsdsocket.library" functions, is to reopen the library for every user. Reopening the library can be costly in terms of memory consumed and time required to initialize library data, so it should be used sparingly. This implementation of the "bsdsocket.library" attempts to allocate very little memory per library base (< 500 bytes). However, using the name/address resolution functionality (such as through the gethostbyname() and gethostbyaddr() functions) and the database functions (getservbyname(), getprotobyname(), etc.) may claim significantly more memory. This implementation of the "bsdsocket.library" specifically denies Processes other than the opener access to the library functions, thus preventing sharing of the resource. Also, Tasks are prevented from calling library functions. The library may not even open for a Task. If your application does not need all clients to use the signal notification mechanisms and is aware of the restrictions, it can enable library base sharing with the SBTC_CAN_SHARE_LIBRARY_BASES feature of the SocketBaseTagList() function. This implementation of "bsdsocket.library" follows the AmiTCP V4.0 API definition. The "V4.0" corresponds to library version 4. INPUTS Name -- The name of the library to open Version -- The version of the library required RESULT Library -- Pointer to a private library base, suitable to call "bsdsocket.library" functions. SEE ALSO SocketBaseTagList(), exec.library/CloseLibrary bsdsocket.library/ProcessIsServer bsdsocket.library/ProcessIsServer NAME ProcessIsServer - Find out if a Process is an Internet server. SYNOPSIS is_server = ProcessIsServer(process) D0 A0 BOOL ProcessIsServer(struct Process * process); FUNCTION Programs can be launched by the Internet superserver. These programs will have sockets associated with them, connected to a client on the network. To find out whether a program was launched in this fashion, use the ProcessIsServer() function. INPUTS process -- Address of a Process to examine, or NULL to use the calling Process' address instead. RESULT is_server -- TRUE if the Process in question was launched from the Internet superserver, FALSE otherwise. NOTES The ProcessIsServer() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_SERVER_API tag with the SocketBaseTagList() function. SEE ALSO ObtainServerSocket() bsdsocket.library/QueryInterfaceTagListsdsocket.library/QueryInterfaceTagList NAME QueryInterfaceTagList - Obtain information on an interface and the associated SANA-II device driver. SYNOPSIS success = QueryInterfaceTagList(name,tags) D0 A0 A1 long QueryInterfaceTagList(STRPTR name,struct TagItem *tags); long QueryInterfaceTags(STRPTR name,...); FUNCTION The QueryInterfaceTagList() will retrieve information about an interface, both referring to stack-internal properties and data accumulated and associated with the underlying SANA-II device driver. INPUTS name -- Name of the interface to be queried. This name cannot be longer than 15 characters. tags -- Pointer to a 'struct TagItem' list. TAGS IFQ_DeviceName (STRPTR *) - Retrieve the name of the SANA-II device associated with this interface. A pointer to the name will be returned. IFQ_DeviceUnit (LONG *) - Retrieve the unit number of the SANA-II device associated with this interface. IFQ_HardwareAddressSize (LONG *) - Retrieve the hardware address size associated with this interface; the number returned will the number of bits in the address. IFQ_HardwareAddress (UBYTE *) - Retrieve the hardware address associated with this interface; a maximum of 16 bytes will be copied. IFQ_MTU (LONG *) - Retrieve the maximum transmission unit size currently associated with this interface; the number of bytes will be returned. Note that this is the MTU value used by the TCP/IP stack, which may be smaller than what the hardware can support. To find out how far the hardware will let you set the MTU value, use the IFQ_HardwareMTU tag. IFQ_HardwareMTU (LONG *) - Retrieve the maximum transmission unit size supported by the driver hardware. This will also magically update the MTU size used by the TCP/IP stack. IFQ_BPS (LONG *) - Retrieve the transmission speed associated with this interface; the number of bits per second will be returned. IFQ_HardwareType (LONG *) - Retrieve the SANA-II hardware type associated with this interface. IFQ_PacketsReceived (ULONG *) - Retrieve the number of packets received by this interface. IFQ_PacketsSent (ULONG *) - Retrieve the number of packets sent by this interface. IFQ_BadData (ULONG *) - Retrieve the number of bad packets dropped by this interface. IFQ_Overruns (ULONG *) - Retrieve the number of buffer overruns registered on this interface. IFQ_UnknownTypes (ULONG *) - Retrieve the number of packets dropped by this interface since their type was not known. IFQ_LastStart (struct timeval *) - Retrieve the time when the interface was last made online. IFQ_Address (struct sockaddr *) - Retrieve the IP address associated with this interface. IFQ_DestinationAddress (struct sockaddr *) - Retrieve the IP address of the point-to-point partner associated with this interface. IFQ_BroadcastAddress (struct sockaddr *) - Retrieve the broadcast address associated with this interface. IFQ_NetMask (struct sockaddr_in *) - Retrieve the subnet mask associated with this interface. IFQ_Metric (LONG *) - Retrieve the routing metric value associated with this interface. IFQ_State (LONG *) - Retrieve the state of the interface; the values returned can be either 'SM_Down' or 'SM_Up'. IFQ_AddressBindType (LONG *) - Find out how the interface address is bound. This can be one of the following: IFABT_Unknown - The address has not been bound or is in transitional state. You should check later to see what state the interface ended up in. IFABT_Static - The address was assigned manually or by an automated configuration process (e.g. BOOTP or DHCP with an infinite lease) and is not expected to change all by itself. IFABT_Dynamic - The address was assigned by an automated configuration process (e.g. DHCP) and may change in the future as part of the configuration process. IFQ_AddressLeaseExpires (struct DateStamp *) - Find out when and if the interface address lease expires. The date stamp will be set to the date and time when the lease will be terminated if no steps were taken to extend it. Normally, leases will be dynamically extended as time goes by. If the date stamp contains all zeroes, it means that the lease lasts infinitely. IFQ_PrimaryDNSAddress (struct sockaddr_in *) - Try to obtain the address of the primary domain name server, if known to this interface. If the address is not known, then the IP address filled in by this tag will be zero. IFQ_SecondaryDNSAddress (struct sockaddr_in *) - Try to obtain the address of the secondary domain name server, if known to this interface. If the address is not known, then the IP address filled in by this tag will be zero. IFQ_NumReadRequests (LONG *) - Query the number of read I/O requests allocated for this interface. IFQ_MaxReadRequests (LONG) - Query the number of read I/O requests in use at a time. IFQ_NumReadRequestsPending (LONG *) - Query the number of read I/O requests pending for this interface, waiting to be satisfied. IFQ_NumWriteRequests (LONG *) - Query the number of write I/O requests allocated for this interface. IFQ_MaxWriteRequests (LONG) - Query the number of write I/O requests in use at a time. IFQ_NumWriteRequestsPending (LONG *) - Query the number of write I/O requests pending for this interface, waiting to be satisfied. IFQ_GetBytesIn (SBQUAD_T *) - Query the number of data bytes received by this interface. This includes both the payload and the header data added by all protocol layers involved. Note that this is an unsigned 64 bit integer. IFQ_GetBytesOut (SBQUAD_T *) - Query the number of data bytes sent by this interface. This includes both the payload and the header data added by all protocol layers involved. Note that this is an unsigned 64 bit integer. IFQ_GetDebugMode (LONG *) - Check if this interface is operating in debugging mode. The result is either TRUE or FALSE. IFQ_GetSANA2CopyStats (struct SANA2CopyStats *) - Obtain statistics covering how often the different SANA-II data transfer functions were invoked so far. The data filled in explains how many times each respective transfer function was called; it does _not_ list the number of bytes transferred. Because the networking device driver is free to ignore the data offered by the DMA transfer functions, the DMA transfer statistics may not be entirely accurate. IFQ_OutputDrops (LONG *) - Query the number of packets dropped before they could get transmitted. IFQ_InputDrops (LONG *) - Query the number of packets which were received, but were dropped before they could be processed. IFQ_OutputErrors (LONG *) - Query the number of errors that were generated during transmission for this interface. IFQ_InputErrors (LONG *) - Query the number of errors that were generated during reception for this interface. IFQ_OutputMulticasts (LONG *) - Query the number of multicasts sent through this interface. IFQ_InputMulticasts (LONG *) - Query the number of multicasts received by this interface. IFQ_IPDrops (LONG *) - Query the total number of all IP packets dropped. IFQ_ARPDrops (LONG *) - Query the total number of all ARP packets dropped. RESULT success -- 0 for success, -1 for failure; the failure code will be stored in the 'errno' variable. NOTES The QueryInterfaceTagList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. The IFQ_PrimaryDNSAddress and IFQ_SecondaryDNSAddress tags require that the underlying device driver supports the SANA-IIR4 extensions, which at this time of writing not many drivers do. Take care. SEE ALSO AddInterfaceTagList(), ConfigureInterfaceTagList() bsdsocket.library/recv bsdsocket.library/recv NAME recv - receive a message from a socket SYNOPSIS #include #include nbytes = recv(s, buf, len, flags) D0 D0 A0 D1 D2 long recv(long s, void *buf, long len, long flags); FUNCTION recvfrom() and recvmsg() are used to receive messages from a socket, and may be used to receive data on a socket whether or not it is connectionoriented. If from is not NULL, and the socket is not connection-oriented, the source address of the message is filled in. Fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. The recv() call is normally used only on a connected socket (see connect()) and is identical to recvfrom() with a NULL from parameter. As it is redundant, it may not be supported in future releases. All three routines return the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket()). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see IoctlSocket()) in which case the value -1 is returned and the external variable errno set to EAGAIN. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(). The WaitSelect() call may be used to determine when more data arrive. The flags argument to a recv call is formed by oring one or more of the values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. The recvmsg() call uses a msghdr structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in : struct msghdr { caddr_t msg_name; /* optional address */ u_int msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter\gather array */ u_int msg_iovlen; /* # elements in msg_iov */ caddr_t msg_control; /* ancillary data, see below */ u_int msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; Here msg_name and msg_namelen specify the destination address if the socket is unconnected; msg_name may be given as a null pointer if no names are desired or required. msg_iov and msg_iovlen describe scatter gather locations. msg_control, which has length msg_controllen, points to a buffer for other protocol control related messages or other miscellaneous ancillary data. The messages are of the form: struct cmsghdr { u_int cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol-specific type */ /* followed by u_char cmsg_data[]; */ }; As an example, one could use this to learn of changes in the data-stream in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting a recvmsg with no data buffer provided immediately after an accept() call. The msg_flags field is set on return according to the message received. MSG_EOR indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_OOB is returned to indicate that expedited or out-of-band data were received. RESULT These calls return the number of bytes received, or -1 if an error occurred. NOTES Technically, "recv(socket,buf,len,flags)" is equivalent to calling "recvfrom(socket,buf,len,flags,NULL,0)". ERRORS The calls fail if: [EBADF] The argument s is an invalid descriptor. [ENOTCONN] The socket is associated with a connection-oriented protocol and has not been connected (see connect() and accept()). [ENOTSOCK] The argument s does not refer to a socket. [EAGAIN] The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. [EINTR] The receive was interrupted by delivery of a signal before any data were available. [EFAULT] The receive buffer pointer(s) point outside the process's address space. SEE ALSO IoctlSocket(), WaitSelect(), getsockopt(), socket() bsdsocket.library/recvfrom bsdsocket.library/recvfrom NAME recvfrom - receive a message from a socket SYNOPSIS #include #include nbytes = recvfrom(s, buf, len, flags, from, fromlen) D0 D0 A0 D1 D2 A1 A2 long recvfrom(long s, void *buf, long len, long flags, struct sockaddr *from,long *fromlen); FUNCTION recvfrom() and recvmsg() are used to receive messages from a socket, and may be used to receive data on a socket whether or not it is connectionoriented. If from is not NULL, and the socket is not connection-oriented, the source address of the message is filled in. Fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. The recv() call is normally used only on a connected socket (see connect()) and is identical to recvfrom() with a NULL from parameter. As it is redundant, it may not be supported in future releases. All three routines return the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket()). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see IoctlSocket()) in which case the value -1 is returned and the external variable errno set to EAGAIN. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(). The WaitSelect() call may be used to determine when more data arrive. The flags argument to a recv call is formed by oring one or more of the values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. The recvmsg() call uses a msghdr structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in : struct msghdr { caddr_t msg_name; /* optional address */ u_int msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter\gather array */ u_int msg_iovlen; /* # elements in msg_iov */ caddr_t msg_control; /* ancillary data, see below */ u_int msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; Here msg_name and msg_namelen specify the destination address if the socket is unconnected; msg_name may be given as a null pointer if no names are desired or required. msg_iov and msg_iovlen describe scatter gather locations. msg_control, which has length msg_controllen, points to a buffer for other protocol control related messages or other miscellaneous ancillary data. The messages are of the form: struct cmsghdr { u_int cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol-specific type */ /* followed by u_char cmsg_data[]; */ }; As an example, one could use this to learn of changes in the data-stream in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting a recvmsg with no data buffer provided immediately after an accept() call. The msg_flags field is set on return according to the message received. MSG_EOR indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_OOB is returned to indicate that expedited or out-of-band data were received. RESULT These calls return the number of bytes received, or -1 if an error occurred. ERRORS The calls fail if: [EBADF] The argument s is an invalid descriptor. [ENOTCONN] The socket is associated with a connection-oriented protocol and has not been connected (see connect() and accept()). [ENOTSOCK] The argument s does not refer to a socket. [EAGAIN] The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. [EINTR] The receive was interrupted by delivery of a signal before any data were available. [EFAULT] The receive buffer pointer(s) point outside the process's address space. SEE ALSO IoctlSocket(), WaitSelect(), getsockopt(), socket() bsdsocket.library/recvmsg bsdsocket.library/recvmsg NAME recvmsg - receive a message from a socket SYNOPSIS #include #include nbytes = recvmsg(s, msg, flags) D0 D0 A0 D1 long recvmsg(long s, struct msghdr *msg, long flags); FUNCTION recvfrom() and recvmsg() are used to receive messages from a socket, and may be used to receive data on a socket whether or not it is connectionoriented. If from is not NULL, and the socket is not connection-oriented, the source address of the message is filled in. Fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. The recv() call is normally used only on a connected socket (see connect()) and is identical to recvfrom() with a NULL from parameter. As it is redundant, it may not be supported in future releases. All three routines return the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket()). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see IoctlSocket()) in which case the value -1 is returned and the external variable errno set to EAGAIN. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(). The WaitSelect() call may be used to determine when more data arrive. The flags argument to a recv call is formed by oring one or more of the values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. The recvmsg() call uses a msghdr structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in : struct msghdr { caddr_t msg_name; /* optional address */ u_int msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter\gather array */ u_int msg_iovlen; /* # elements in msg_iov */ caddr_t msg_control; /* ancillary data, see below */ u_int msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; Here msg_name and msg_namelen specify the destination address if the socket is unconnected; msg_name may be given as a null pointer if no names are desired or required. msg_iov and msg_iovlen describe scatter gather locations. msg_control, which has length msg_controllen, points to a buffer for other protocol control related messages or other miscellaneous ancillary data. The messages are of the form: struct cmsghdr { u_int cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol-specific type */ /* followed by u_char cmsg_data[]; */ }; As an example, one could use this to learn of changes in the data-stream in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting a recvmsg with no data buffer provided immediately after an accept() call. The msg_flags field is set on return according to the message received. MSG_EOR indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_OOB is returned to indicate that expedited or out-of-band data were received. RESULT These calls return the number of bytes received, or -1 if an error occurred. ERRORS The calls fail if: [EBADF] The argument s is an invalid descriptor. [ENOTCONN] The socket is associated with a connection-oriented protocol and has not been connected (see connect() and accept()). [ENOTSOCK] The argument s does not refer to a socket. [EAGAIN] The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. [EINTR] The receive was interrupted by delivery of a signal before any data were available. [EFAULT] The receive buffer pointer(s) point outside the process's address space. SEE ALSO IoctlSocket(), WaitSelect(), getsockopt(), socket() bsdsocket.library/ReleaseCopyOfSocket bsdsocket.library/ReleaseCopyOfSocket NAME ReleaseCopyOfSocket - duplicate a socket descriptor, then release the duplicate to the public list SYNOPSIS id = ReleaseCopyOfSocket(fd, Id) D0 D0 D1 long ReleaseCopyOfSocket(long fd, long Id); FUNCTION This function is for passing control of a socket from one process to another. INPUTS fd - The descriptor associated with the socket whose duplicate is to be released id - The key value to associate the duplicate with. If the id value is between 0 and 65535 (inclusively), then the id is considered non-unique and anyone can pick it up via ObtainSocket() by specifying the right combination of socket type and protocol. If the id value is greater than 65535 then it must be unique number (this function will fail if it is not). If the id value matches the constant UNIQUE_ID then this function will generate a unique id and return it. RESULT A -1 is returned if an error occurs, otherwise the return value is the Id with which the socket has been associated. ERRORS The ReleaseCopyOfSocket() call fails if: [ENOMEM] There is not enough memory left to put this socket onto the public list. [EINVAL] The Id number requested is not unique. [EBADF] The socket descriptor number is not valid. [EMFILE] Too many descriptors are active. SEE ALSO socket(), accept(), bind(), connect(), getsockname(), getsockopt(), IoctlSocket(), listen(), recv(), WaitSelect(), send(), shutdown(), ObtainSocket(), ReleaseSocket(), Dup2Socket() bsdsocket.library/ReleaseDomainNameServerListrary/ReleaseDomainNameServerList NAME ReleaseDomainNameServerList - Release a list of local domain server addresses as returned by ObtainDomainNameServerList(). SYNOPSIS ReleaseDomainNameServerList(list) A0 void ReleaseDomainNameServerList(struct List *list); FUNCTION ReleaseDomainNameServerList() is the counterpart to ObtainDomainNameServerList() and will release the list returned by it. INPUTS list -- Pointer to a list as returned by ObtainDomainNameServerList(). This can be NULL in which case this routine will do nothing. NOTES The ReleaseDomainNameServerList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_DNS_API tag with the SocketBaseTagList() function. SEE ALSO ObtainDomainNameServerList() bsdsocket.library/ReleaseInterfaceList bsdsocket.library/ReleaseInterfaceList NAME ReleaseInterfaceList - Release a list of available interfaces, as returned by ObtainInterfaceList(). SYNOPSIS ReleaseInterfaceList(list) A0 void ReleaseInterfaceList(struct List *list); FUNCTION ReleaseInterfaceList() is the counterpart to ObtainInterfaceList() and will release the list returned by it. INPUTS list -- Pointer to a list as returned by ObtainInterfaceList(). This can be NULL in which case this routine will do nothing. NOTES The ReleaseInterfaceList() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. SEE ALSO ObtainInterfaceList() bsdsocket.library/ReleaseRoadshowData bsdsocket.library/ReleaseRoadshowData NAME ReleaseRoadshowData - Release access to internal Roadshow configuration data. SYNOPSIS ReleaseRoadshowData(list) D0 VOID ReleaseRoadshowData(struct List *list); FUNCTION Several internal options control how the TCP/IP stack works. These do not normally need to be changed, but there are times when you might want to override or check them. ObtainRoadshowData() gives you access to the list of known configurable options. ReleaseRoadshowData() complements it by releasing access to it. INPUTS list -- The list pointer you received by calling the ObtainRoadshowData() function. If this is NULL, it will be ignored. NOTES The ObtainRoadshowData() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_ROADSHOWDATA_API tag with the SocketBaseTagList() function. SEE ALSO ObtainRoadshowData(), ChangeRoadshowData() bsdsocket.library/ReleaseSocket bsdsocket.library/ReleaseSocket NAME ReleaseSocket - release a socket to the public list SYNOPSIS id = ReleaseSocket(fd, Id) D0 D0 D1 long ReleaseSocket(long fd, long Id); FUNCTION This function is for passing control of a socket from one process to another. INPUTS fd - The descriptor associated with the socket to be released Id - The key value to associate this socket with. If the Id value is between 0 and 65535 (inclusively), then the id is considered non-unique and anyone can pick it up via ObtainSocket() by specifying the right combination of socket type and protocol. If the Id value is greater than 65535 then it must be unique number (this function will fail if it is not). If the Id value matches the constant UNIQUE_ID then this function will generate a unique id and return it. RESULT A -1 is returned if an error occurs, otherwise the return value is the Id with which the socket has been associated. ERRORS The ReleaseSocket() call fails if: [ENOMEM] There is not enough memory left to put this socket onto the public list. [EINVAL] The Id number requested is not unique. [EBADF] The socket descriptor number is not valid. SEE ALSO socket(), accept(), bind(), connect(), getsockname(), getsockopt(), IoctlSocket(), listen(), recv(), WaitSelect(), send(), shutdown(), ObtainSocket(), CloseSocket() bsdsocket.library/RemoveDomainNameServersocket.library/RemoveDomainNameServer NAME RemoveDomainNameServer - Remove a domain name server address from the local resolver database. SYNOPSIS success = RemoveDomainNameServer(address) D0 A0 LONG RemoveDomainNameServer(STRPTR address); FUNCTION RemoveDomainNameServer() removes an address from the local resolver database. This does not modify the on-disk resolver database, the change only affects the in-memory copy. INPUTS address -- Domain name server address as a pointer to a NUL-terminated string; the address must be given in dotted-decimal notation (per RFC1700). RESULT If the address could be removed, a 0 value is returned. A return value of -1 indicates an error, which is further specified in the global errno. ERRORS The RemoveDomainNameServer() call will fail if: [ENOBUFS] There was not enough memory left to add a new database entry. [ENOENT] The IP address to remove was not found. [EFAULT] The address parameter is not valid. NOTES The AddDomainNameServer() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_DNS_API tag with the SocketBaseTagList() function. SEE ALSO AddDomainNameServer(), SocketBaseTagList() bsdsocket.library/RemoveInterface bsdsocket.library/RemoveInterface NAME RemoveInterface - Pull a network interface out of circulation SYNOPSIS success = RemoveInterface(name,force) D0 A0 D0 BOOL RemoveInterface(STRPTR name,BOOL force); FUNCTION This is the counterpart to AddInterface(). It tries to release all the resources associated with a networking interface, thus permitting it to be added again with new parameters. INPUTS name -- Unique name of the interface, assigned at the time it was originally added. force -- RemoveInterface() will refuse to remove an interface which is still in use. Use a 'force' parameter of TRUE to make it remove the interface anyway. Note that if you force an interface to be removed memory may remain allocated until you shut down the network (with the "NetShutdown" command). RESULT success -- TRUE for success, 0 for failure; the failure code will be stored in the 'errno' variable. NOTES The RemoveInterface() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_INTERFACE_API tag with the SocketBaseTagList() function. SEE ALSO AddInterfaceTagList() bsdsocket.library/RemoveNetMonitorHook bsdsocket.library/RemoveNetMonitorHook NAME RemoveNetMonitorHook - Remove a network monitoring callback hook previously installed with AddNetMonitorHookTagList(). SYNOPSIS RemoveNetMonitorHook(hook) A0 VOID RemoveNetMonitorHook(struct Hook *hook); FUNCTION This function will remove a network monitoring hook that was previously installed with AddNetMonitorHookTagList(). It must be called before the library is closed, or the library will stay in memory indefinitely. INPUTS hook -- Pointer to the Hook previously installed; this may be NULL in which case this function does nothing. NOTES The RemoveNetMonitorHook() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_MONITORING_API tag with the SocketBaseTagList() function. SEE ALSO AddNetMonitorHookTagList() bsdsocket.library/send bsdsocket.library/send NAME send - send a message from a socket SYNOPSIS #include #include nbytes = send(s, msg, len, flags) D0 D0 A0 D1 D2 long send(long s, void *msg, long len, long flags); FUNCTION send(), sendto(), and sendmsg() are used to transmit a message to another socket. Send() may be used only when the socket is in a connected state, while sendto() and sendmsg() may be used at any time. The address of the target is given by to with tolen specifying its size. The length of the message is given by len. If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a send(). Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then send() normally blocks, unless the socket has been placed in non-blocking I/O mode. The WaitSelect() call may be used to determine when it is possible to send more data. The flags parameter may include one or more of the following: #define MSG_OOB 0x1 /* process out-of-band data */ #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support ``out-of-band'' data. MSG_DONTROUTE is usually used only by diagnostic or routing programs. See recv() for a description of the msghdr structure. RESULT The call returns the number of characters sent, or -1 if an error occurred. NOTES Technically, "send(socket,buf,len,flags)" is equivalent to calling "sendto(socket,buf,len,flags,NULL,0)". ERRORS send(), sendto(), and sendmsg() fail if: [EBADF] An invalid descriptor was specified. [ENOTSOCK] The argument s is not a socket. [EFAULT] An invalid user space address was specified for a parameter. [EMSGSIZE] The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. SEE ALSO IoctlSocket(), recv(), WaitSelect(), getsockopt(), socket() bsdsocket.library/sendmsg bsdsocket.library/sendmsg NAME sendmsg - send a message from a socket SYNOPSIS #include #include nbytes = sendmsg(s, msg, flags) D0 D0 A0 D1 long sendmsg(long s, struct msghdr *msg, long flags); FUNCTION send(), sendto(), and sendmsg() are used to transmit a message to another socket. Send() may be used only when the socket is in a connected state, while sendto() and sendmsg() may be used at any time. The address of the target is given by to with tolen specifying its size. The length of the message is given by len. If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a send(). Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then send() normally blocks, unless the socket has been placed in non-blocking I/O mode. The WaitSelect() call may be used to determine when it is possible to send more data. The flags parameter may include one or more of the following: #define MSG_OOB 0x1 /* process out-of-band data */ #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support ``out-of-band'' data. MSG_DONTROUTE is usually used only by diagnostic or routing programs. See recv() for a description of the msghdr structure. RESULT The call returns the number of characters sent, or -1 if an error occurred. ERRORS send(), sendto(), and sendmsg() fail if: [EBADF] An invalid descriptor was specified. [ENOTSOCK] The argument s is not a socket. [EFAULT] An invalid user space address was specified for a parameter. [EMSGSIZE] The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. SEE ALSO IoctlSocket(), recv(), WaitSelect(), getsockopt(), socket() bsdsocket.library/sendto bsdsocket.library/sendto NAME sendto - send a message from a socket SYNOPSIS #include #include nbytes = sendto(s, msg, len, flags, to, tolen) D0 D0 A0 D1 D2 A1 D3 long sendto(long s, void *msg, long len, long flags, struct sockaddr *to, long tolen); FUNCTION send(), sendto(), and sendmsg() are used to transmit a message to another socket. Send() may be used only when the socket is in a connected state, while sendto() and sendmsg() may be used at any time. The address of the target is given by to with tolen specifying its size. The length of the message is given by len. If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a send(). Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then send() normally blocks, unless the socket has been placed in non-blocking I/O mode. The WaitSelect() call may be used to determine when it is possible to send more data. The flags parameter may include one or more of the following: #define MSG_OOB 0x1 /* process out-of-band data */ #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support ``out-of-band'' data. MSG_DONTROUTE is usually used only by diagnostic or routing programs. See recv() for a description of the msghdr structure. RESULT The call returns the number of characters sent, or -1 if an error occurred. ERRORS send(), sendto(), and sendmsg() fail if: [EBADF] An invalid descriptor was specified. [ENOTSOCK] The argument s is not a socket. [EFAULT] An invalid user space address was specified for a parameter. [EMSGSIZE] The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. SEE ALSO IoctlSocket(), recv(), WaitSelect(), getsockopt(), socket() bsdsocket.library/SetDefaultDomainName bsdsocket.library/SetDefaultDomainName NAME SetDefaultDomainName - Configure the domain name that will be added to the end of host names which lack a domain name. SYNOPSIS SetDefaultDomainName(name) A0 VOID SetDefaultDomainName(STRPTR name); FUNCTION If no domain name is part of a host name, a default domain name can be added to it if the host name lookup fails. This is normally controlled by the name server configuration file but may be overridden either through an environment variable or a call to SetDefaultDomainName(). INPUTS name -- The default domain name (as per RFC 1035). This cannot be longer than 255 characters in total and preferrably should be much shorter. Only a single domain name can be configured here. If you need more, either use the LOCALDOMAIN environment variable or edit the file "DEVS:Internet/name_resolution". NOTES The SetDefaultDomainName() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_DNS_API tag with the SocketBaseTagList() function. SEE ALSO GetDefaultDomainName(), SocketBaseTagList() bsdsocket.library/SetErrnoPtr bsdsocket.library/SetErrnoPtr NAME SetErrnoPtr - set the reference to the errno variable SYNOPSIS SetErrnoPtr(errno_ptr, size) A0 D0 void SetErrnoPtr(void *errno_ptr, long size); FUNCTION This function is deprecated; SocketBaseTags() with the SBTC_ERRNOPTR tag should be used instead. This function is for linking an program's local 'errno' variable to the kernel's error code state information, as set when a function call fails. INPUTS errno_ptr - Pointer to the local program's 'errno' variable, e.g. '&errno'. size - Size of the local program's 'errno' variable, e.g. 'sizeof(errno)'. SEE ALSO Errno() bsdsocket.library/setnetent bsdsocket.library/setnetent NAME setnetent - get network entry SYNOPSIS #include setnetent(stayopen) D0 void setnetent(int stayopen); FUNCTION The setnetent() function opens and 'rewinds' the net database. If the 'stayopen' flag is non-zero, the net data base will not be closed after each call to getnetbyname() or getnetbyaddr(). SEE ALSO getnetent(), getnetbyaddr(), getnetbyname(), endnetent() BUGS The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. NOTES The setnetent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/setprotoent bsdsocket.library/setprotoent NAME setprotoent - get protocol entry SYNOPSIS #include setprotoent(stayopen) D0 void setprotoent(LONG stayopen); FUNCTION The setprotoent() function opens and 'rewinds' the protocol database. If the 'stayopen' flag is non-zero, the protocol data base will not be closed after each call to getprotobyname() or getprotobynumber(). SEE ALSO getprotoent(), getprotobynumber(), getprotobyname(), endprotoent() BUGS These functions use a static data space; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet protocols are currently understood. NOTES The setprotoent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/setservent bsdsocket.library/setservent NAME setservent - get service entry SYNOPSIS #include setservent(stayopen) D0 void setservent(LONG stayopen); FUNCTION The setservent() function opens and 'rewinds' the service database. If the 'stayopen' flag is non-zero, the database will not be closed after each call to getservbyname() or getservbyport(). SEE ALSO getservent(), getservbyname(), getservbyport(), endservent() BUGS These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Expecting port numbers to fit in a 32 bit quantity is probably naive. NOTES The setservent() call is an extension to the AmiTCP V4 API and cannot be assumed to be present in all versions of "bsdsocket.library". To find out whether your library version supports it, use the SBTC_HAVE_LOCAL_DATABASE_API tag with the SocketBaseTagList() function. bsdsocket.library/SetSocketSignals bsdsocket.library/SetSocketSignals NAME SetSocketSignals - set the signals to be sent for socket events SYNOPSIS SetSocketSignals(int_mask, io_mask, urgent_mask) D0 D1 D2 void SetSocketSignals(ULONG int_mask, ULONG io_mask, ULONG urgent_mask); FUNCTION This function is deprecated. SocketBaseTags() should be used instead with the SBTC_BREAKMASK, SBTC_SIGIOMASK and SBTC_SIGURGMASK tags. The purpose of this function is to associate Exec signal masks with the Unix signals SIGINT (= int_mask), SIGIO (= io_mask) and SIGURG (= urgent_mask). SIGINT is the signal to send to the process which owns the socket in order to abort a blocking operation, such as recv(). SIGIO is the signal which will be sent to the owner of the socket when an asynchronous notification of socket events arrives. SIGURG is the signal which will be sent to the owner of the socket when out-of-band data arrives. SEE ALSO IoctlSocket(), recv(), send(), WaitSelect() bsdsocket.library/setsockopt bsdsocket.library/setsockopt NAME setsockopt - set options on sockets SYNOPSIS #include #include success = setsockopt(s, level, optname, optval, optlen) D0 D0 D1 D2 A0 D3 long setsockopt(long s, long level, long optname, void *optval, long optlen); FUNCTION getsockopt() and setsockopt() manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost ``socket'' level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP. The parameters optval and optlen are used to access option values for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, optval may be NULL. Optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. Most socket-level options utilize an int parameter for optval. For setsockopt(), the parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. SO_LINGER uses a struct linger parameter, defined in , which specifies the desired state of the option and the linger interval (see below). SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parameter, defined in . The following options are recognized at the socket level. Except as noted, each may be examined with getsockopt() and set with setsockopt(). SO_DEBUG enables recording of debugging information SO_REUSEADDR enables local address reuse SO_REUSEPORT enables duplicate address and port bindings SO_KEEPALIVE enables keep connections alive SO_DONTROUTE enables routing bypass for outgoing messages SO_LINGER linger on close if data present SO_BROADCAST enables permission to transmit broadcast messages SO_OOBINLINE enables reception of out-of-band data in band SO_SNDBUF set buffer size for output SO_RCVBUF set buffer size for input SO_SNDLOWAT set minimum count for output SO_RCVLOWAT set minimum count for input SO_SNDTIMEO set timeout value for output SO_RCVTIMEO set timeout value for input SO_TYPE get the type of the socket (get only) SO_ERROR get and clear error on the socket (get only) SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind() call should allow reuse of local addresses. SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. SO_LINGER controls the action taken when unsent messages are queued on socket and a CloseSocket() is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in seconds in the setsockopt() call when SO_LINGER is requested). If SO_LINGER is disabled and a close is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The option SO_BROADCAST requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv or read calls without the MSG_OOB flag. Some protocols always behave as if this option is set. SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. SO_SNDLOWAT is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A WaitSelect() operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for SO_SNDLOWAT is set to a convenient size for network efficiency, often 1024. SO_RCVLOWAT is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with the smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error EWOULDBLOCK if no data were sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error EWOULDBLOCK if no data were received. Finally, SO_TYPE and SO_ERROR are options used only with getsockopt(). SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful for servers that inherit sockets on startup. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. RESULT A 0 is returned if the call succeeds, -1 if it fails. ERRORS The call succeeds unless: [EBADF] The argument s is not a valid descriptor. [ENOTSOCK] The argument s is a file, not a socket. [ENOPROTOOPT] The option is unknown at the level indicated. [EFAULT] The address pointed to by optval is not in a valid part of the process address space. For getsockopt(), this error may also be returned if optlen is not in a valid part of the process address space. SEE ALSO IoctlSocket(), socket(), ip bsdsocket.library/shutdown bsdsocket.library/shutdown NAME shutdown - shut down part of a full-duplex connection SYNOPSIS #include success = shutdown(s, how) D0 D0 D1 long shutdown(long s, long how); FUNCTION The shutdown() call causes all or part of a full-duplex connection on the socket associated with s to be shut down. If how is 0, further receives will be disallowed. If how is 1, further sends will be disallowed. If how is 2, further sends and receives will be disallowed. RESULT A 0 is returned if the call succeeds, -1 if it fails. ERRORS The call succeeds unless: [EBADF] s is not a valid descriptor. [ENOTSOCK] s is a file, not a socket. [ENOTCONN] The specified socket is not connected. SEE ALSO connect(), socket() bsdsocket.library/socket bsdsocket.library/socket NAME socket - create an endpoint for communication SYNOPSIS #include #include s = socket(domain, type, protocol) D0 D0 D1 D2 long socket(long domain, long type, long protocol); FUNCTION socket() creates an endpoint for communication and returns a descriptor. The domain parameter specifies a communications domain within which communication will take place; this selects the protocol family which should be used. These families are defined in the include file . The only supported domain is: AF_INET ARPA Internet protocols The socket has the indicated type, which specifies the semantics of communication. Currently defined types are: SOCK_STREAM SOCK_DGRAM SOCK_RAW SOCK_SEQPACKET SOCK_RDM A SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams. An out-of-band data transmission mechanism may be supported. A SOCK_DGRAM socket supports datagrams (connectionless, unreliable messages of a fixed (typically small) maximum length). A SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer may be required to read an entire packet with each read system call. This facility is protocol specific, and presently implemented only for PF_NS. SOCK_RAW sockets provide access to internal network protocols and interfaces. The types SOCK_RAW, which is available only to the super-user, and SOCK_RDM, which is planned, but not yet implemented, are not described here. The protocol specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type within a given protocol family. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner. The protocol number to use is particular to the communication domain in which communication is to take place. Sockets of type SOCK_STREAM are full-duplex byte streams, similar to pipes. A stream socket must be in a connected state before any data may be sent or received on it. A connection to another socket is created with a connect() call. Once connected, data may be transferred using some variant of the send() and recv() calls. When a session has been completed a CloseSocket() may be performed. Out-of-band data may also be transmitted as described in send() and received as described in recv(). The communications protocols used to implement a SOCK_STREAM insure that data is not lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls will indicate an error with -1 returns and with ETIMEDOUT as the specific code in the global variable errno. The protocols optionally keep sockets ``warm'' by forcing transmissions roughly every minute in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise idle connection for a extended period (e.g. 5 minutes). SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sockets. The only difference is that recv() calls will return only the amount of data requested, and any remaining in the arriving packet will be discarded. SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspondents named in send() calls. Datagrams are generally received with recvfrom(), which returns the next datagram with its return address. An IoctlSocket() call can be used to specify a process group to receive a SIGURG signal when the out-of-band data arrives. It may also enable nonblocking I/O and asynchronous notification of I/O events via SIGIO. The operation of sockets is controlled by socket level options. These options are defined in the file . setsockopt() and getsockopt() are used to set and get options, respectively. RESULT A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. ERRORS The socket() call fails if: [EPROTONOSUPPORT] The protocol type or the specified protocol is not supported within this domain. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [EACCESS] Permission to create a socket of the specified type and/or protocol is denied. [ENOBUFS] Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed. SEE ALSO accept(), bind(), connect(), getsockname(), getsockopt(), IoctlSocket(2), listen(), recv(), WaitSelect(), send(), shutdown(), icmp, tcp, udp bsdsocket.library/SocketBaseTagList bsdsocket.library/SocketBaseTagList NAME SocketBaseTagList - get/set global library attributes SYNOPSIS result = SocketBaseTagList(tags) D0 A0 long SocketBaseTagList(struct TagItem *tags); long SocketBaseTags(Tag first_tag, ...); FUNCTION This function is for querying and changing attributes of the stack's state information. The header file defines macros for base tag code values. Base tag code macro names begin with `SBTC_' (as in 'Socket Base Tag Code'). The base tag value defines the data item which the tag item refers to. The tag code contains other information besides the referred data item. It controls whether the SocketBaseTagList() should set or get the appropriate parameter, and whether the argument of the tag in question is passed by value or by reference. The header file defines the following macros, which are used to construct the ti_Tag values from the base tag codes: SBTM_GETREF(code) - get by reference SBTM_GETVAL(code) - get by value SBTM_SETREF(code) - set by reference SBTM_SETVAL(code) - set by value If the actual data is stored directly in the ti_Data field, you should use the 'by value' macros, SBTM_GETVAL() or SBTM_SETVAL(). This is not recommended since it runs counter to the TagItem concept. However, if the ti_Data field contains a pointer to actual data, you should use the 'by reference' macros, SBTM_GETREF() or SBTM_SETREF(). In either case the actual data should always be a LONG aligned to an even address. According the tag naming scheme a tag which has a "PTR" suffix takes a pointer as its argument. Don't mix the pointer arguments with 'by reference' argument passing. It is possible to pass a pointer by reference (in which case the ti_Data is a pointer to the actual pointer). The list of all defined base tag codes is as follows: SBTC_SIG_ADDRESS_CHANGE_MASK Tag data contains the Exec signal mask to be sent when an interface address has changed. The receiver is responsible for figuring out what exactly has changed and whether the change needs reacting to. Default for this mask is 0, i.e. no notification will be sent. This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. SBTC_BREAKMASK Tag data contains the Exec signal mask to be associated with the Unix SIGINT signal. By default, this is SIGBREAKF_CTRL_C. SBTC_CAN_SHARE_LIBRARY_BASES This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. Normally, every client to call "bsdsocket.library" routines will have to reopen the library and obtain its own instance of the per-library base variables. The SBTC_CAN_SHARE_LIBRARY_BASES tag can be used to allow several Tasks/Processes to share a single library base. Note that error reporting will become rather difficult if you do this, as there is only one instance of the library state variables per base. Also, the signal delivery mechanisms behind SBTC_SIGIOMASK, SBTC_SIGEVENTMASK and SBTC_SIGURGMASK will only work for the Process that configured them. This option only has local impact in that it affects only the single library base for which it was configured. SBTC_DTABLESIZE Tag data contains the number of entries in the socket descriptor table. This number indicates how many sockets may be use at a time per process. For Roadshow, the default is 256 sockets. Other TCP/IP stacks may use a smaller number. SBTC_ERRNO The value of the 'errno' state variable. SBTC_ERRNOBYTEPTR SBTC_ERRNOWORDPTR SBTC_ERRNOLONGPTR SBTC_ERRNOPTR(size) Link the program's global 'errno' variable to the protocol stack's internal errno variable, by passing a pointer to the program's variable to the protocol stack. The SBTC_ERRNOPTR(size) is a macro, which expands to one of the other (BYTE, WORD or LONG) tag codes, meaning that only 1, 2 and 4 are legal size values. SBTC_ERRNOSTRPTR The error string corresponding to an error code. The tag is used both for input and output: in goes the error code (a pointer to an integer), out goes a pointer to the corresponding error string. SBTC_ERROR_HOOK Install or remove a hook which is called whenever the global 'errno' or 'h_errno' variables are changed. The hook is always called on the context of the caller and can be used together with SBTC_CAN_SHARE_LIBRARY_BASES feature to safely deliver the error codes to concurrent processes. The hook will be called with the following parameters: error = hookfunc(hook,reserved,ehm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct ErrorHookMsg *ehm); The 'reserved' parameter will be set to NULL for future expansion. The contents of the ErrorHookMsg are as follows: ehm_Size Size of the data structure in bytes. This May grow in future releases. Always make sure to verify that the message size is exactly as you expected it. ehm_Action This can be EHMA_Set_errno, or EHMA_Set_h_errno, indicating which variable should be changed. Any other value should be ignored. ehm_Code The error code to be set. The SBTC_ERROR_HOOK tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. SBTC_FDCALLBACK This function is deprecated and should not used by new code. Install a callback hook that is called by the kernel whenever the file descriptor table is modified. SBTC_GET_BYTES_RECEIVED Obtain the number of bytes received by the TCP/IP stack. The parameter must be of type 'SBQUAD_T'. Note that the data must be passed by reference. Older version of "bsdsocket.library" may return a failure code when querying this option. SBTC_GET_BYTES_SENT Obtain the number of bytes sent by the TCP/IP stack. The parameter must be of type 'SBQUAD_T'. Note that the data must be passed by reference. Older version of "bsdsocket.library" may return a failure code when querying this option. SBTC_HAVE_ADDRESS_CONVERSION_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the address conversion API functions, such as inet_aton(), inet_ntop() and inet_pton(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the address conversion API is supported, and FALSE or failure otherwise. SBTC_HAVE_DNS_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the DNS API functions, such as AddDomainNameServer() and RemoveDomainNameServer(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the DNS API is supported, and FALSE or failure otherwise. SBTC_HAVE_INTERFACE_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the interface API functions, such as AddInterfaceTagList() and ConfigureInterfaceTagList(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the interface API is supported, and FALSE or failure otherwise. SBTC_HAVE_KERNEL_MEMORY_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the kernel memory API functions, such as mbuf_copym(), mbuf_free() or mbuf_mget(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the kernel memory API is supported, and FALSE or failure otherwise. SBTC_HAVE_LOCAL_DATABASE_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the local database access API functions, setnetent() and getprotoent(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the local database access API is supported, and FALSE or failure otherwise. SBTC_HAVE_MONITORING_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the interface API functions, such as AddNetMonitorHookTagList() and RemoveNetMonitorHook(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the monitoring API is supported, and FALSE or failure otherwise. SBTC_HAVE_ROADSHOWDATA_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the RoadshowData API functions, such as ObtainRoadshowData() and ReleaseRoadshowData(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the RoadshowData API is supported, and FALSE or failure otherwise. SBTC_HAVE_ROUTING_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the routing API functions, such as AddRouteTagList() and DeleteRouteTagList(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the routing API is supported, and FALSE or failure otherwise. SBTC_HAVE_SERVER_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the server API functions, such as ProcessIsServer() and ObtainServerSocket(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the server API is supported, and FALSE or failure otherwise. SBTC_HAVE_STATUS_API This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the interface API functions, such as GetNetworkStatistics(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return TRUE if the status API is supported, and FALSE or failure otherwise. SBTC_HERRNO The current value of the h_errno variable which contains the error code from the resolver. Note: the protocol stack assumes that sizeof(h_errno) == sizeof(long). SBTC_HERRNOSTRPTR The error string corresponding to a resolver error code. The tag is used both for input and output: in goes the error code (a pointer to an integer), out goes a pointer to the corresponding error string. SBTC_ICMP_MASK_REPLY This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and changing whether ICMP address mask requests will be answered. This option is disabled by default. SBTC_ICMP_PROCESS_ECHO This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and changing how the stack should process an incoming ICMP echo request (such as sent by the 'ping' utility). The following reactions are possible: IR_Process The request will be processed and a corresponding ICMP_ECHOREPLY message will be sent. IR_Ignore The request will be ignored, but fed into the raw IP packet processing framework. IR_Drop The request will be ignored and treated as if it had a checksum error. The default is IR_Process. Note that this option affects the entire protocol stack and is not limited to the library base you set it with. SBTC_ICMP_PROCESS_TSTAMP This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and changing how the stack should process an incoming ICMP time stamp request. The following reactions are possible: IR_Process The request will be processed and a corresponding ICMP_TSTAMPREPLY message will be sent. IR_Ignore The request will be ignored, but fed into the raw IP packet processing framework. IR_Drop The request will be ignored and treated as if it had a checksum error. The default is IR_Process. Note that this option affects the entire protocol stack and is not limited to the library base you set it with. SBTC_ICMP_SEND_REDIRECTS This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and changing whether ICMP redirect messages will be sent when forwarding IP datagrams. This option is enabled by default, but will have no effect unless the protocol stack is configured to forward IP datagrams (using the SBTC_IP_FORWARDING option). Note that this option affects the entire protocol stack and is not limited to the library base you set it with. SBTC_IDN_DEFAULT_CHARACTER_SET This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. "Roadshow" can perform international domain name translations during host name and IP resolution. This takes place on the fly without the application really noticing what happened. To perform this translation, it must be known which character set the domain names should be represented in. By default, this is the native Amiga ISO 8859 Latin 1 character set. Possible choices are: IDNCS_ASCII Do not perform any translation; this leaves this task to the application calling the name resolution functions. IDNCS_ISO_8859_LATIN_1 This is the default. Perform translations using the ISO 8859 Latin 1 character set; if this translation is not possible, return the domain name unchanged. More character sets may be added in future releases. Note that if the library does not understand the character set code you select, then it will behave as if IDNCS_ASCII had been selected. SBTC_IOERRNOSTRPTR This function is deprecated and should not used by new code. The error string corresponding to an Exec I/O error code. The tag is used both for input and output: in goes the error code (a pointer to a positive integer), out goes a pointer to the corresponding error string. SBTC_IPF_API_VERSION This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the IP filter API functions, such as ipf_open() and ipf_ioctl(). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag can be used to query if the IP filter API is implemented, and which version of that API is available. Version numbers that do not exactly match the number you expected must be rejected. Future version of the IP filter may use different data structures and/or drop existing functionality. Older version of "bsdsocket.library" may return a failure code when querying this option. Because the IP filter API is subject to change, it is intentionally not documented or otherwise supported by public source code. SBTC_IP_FILTER_HOOK This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and installing a hook that will be called for every datagram that arrives and for every datagram to be sent. To remove a hook that was installed, install one with an address of NULL. The hook will be called with the following parameters: error = hookfunc(hook,reserved,ifm) D0 A0 A2 A1 LONG hookfunc(struct Hook *hook, APTR reserved, struct IPFilterMsg *ifm); The 'reserved' parameter will be set to NULL for future expansion. The contents of the IPFilterMsg are as follows: ifm_Size Size of the data structure in bytes. This May grow in future releases. Always make sure to verify that the message size is exactly as you expected it. ifm_IP Pointer to the IP packet header. ifm_IPLength Size of the IP packet header in bytes. ifm_Interface Refers to the interface the packet either arrived at or is about to be sent to. ifm_Direction This indicates whether the packet submitted to your filter has arrived (IFMD_Incoming) or is about to be sent (IFMD_Outgoing). ifm_Packet Points to the packet to be sent, as stored in an linked list of memory buffer structures (mbufs). Your hook function must evaluate the contents of the packet and, based upon that evaluation, return an error code. If that error code (see ) is non-zero, the packet will be dropped. That is, it will either not enter the TCP/IP stack's processing (IFMD_Incoming) or it will not be sent (IFMD_Outgoing). Return 0 if the packet may pass. You must perform your filtering as quickly as possible because your hook function will be invoked by the kernel itself and data processing may be be delayed otherwise. The contents of the IPFilterMsg are essentially read-only, but if you must, you can make modifications to the ifm_Packet data. If you do so, you *must* make a copy of the packet, release the old packet and put the address of the modified copy into the ifm_Packet field. You can also force a packet to be dropped by setting the ifm_Packet field to NULL. To make copies of packets, to extract information from them or to release them, you must use the kernel memory API. SBTC_IP_FORWARDING This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and changing whether IP datagrams will be forwarded or not. This option is disabled by default which means that IP datagrams are not forwarded. Note that this option affects the entire protocol stack and is not limited to the library base you set it with. SBTC_IP_DEFAULT_TTL This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and changing the default IP packet TTL value. The default value is 64 (per RFC 1340). Note that this option affects the entire protocol stack and is not limited to the library base you set it with. SBTC_LOGFACILITY Facility code for the syslog messages as defined in the header file . Defaults to LOG_USER. SBTC_LOG_FILE_NAME This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag can be used to alter or query the name of the file log messages will be sent to. To change the name, pass in a pointer to the new file name; it will be copied. To find out what the current name is, post a query request; you will receive a pointer to the string containing the name. The size of the name buffer is limited to about 510 characters. File names longer than this will be truncated. An empty file name has the effect of turning log message reporting off entirely. If the output file is not a console window, then any new messages will be appended to the existing log file. Note that this option affects the entire protocol stack and is not limited to the library base you set it with. SBTC_LOG_HOOK This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. The logging mechanism can call a hook rather than sending log messages to the process which records and displays them. It's this hook which can be installed or queried using this tag. Installing a NULL pointer in place of a hook will cause logging messages to be displayed and recorded again. Note that the hook will be invoked on the context of the process which called into 'vsyslog()', which may be the TCP/IP stack itself. You should therefore process the message as quickly as possible. The hook will be called with the following parameters: hookfunc(hook,reserved,lhm) A0 A2 A1 VOID hookfunc(struct Hook *hook, APTR reserved, struct LogHookMessage *lhm); The 'reserved' parameter will be set to NULL for future expansion. The contents of the LogHookMessage are read-only and must not be modified. SBTC_LOGMASK Sets the filter mask of the syslog messages. By default the mask is 0xFF, meaning that all messages are passed to the logging system. SBTC_LOGSTAT Syslog options as defined in . SBTC_LOGTAGPTR A pointer to a string which is used by syslog() to mark individual syslog messages. This defaults to NULL. SBTC_NUM_PACKET_FILTER_CHANNELS This tag is an extension to the AmiTCP V4 API and must be used prior to calling any of the Berkeley packet filter functions (e.g. bpf_open(), bpf_close(), etc.). Since older "bsdsocket.library" implementations do not process this tag you should be prepared to handle failure of the query operation. This tag will return the number of Berkeley packet filter channels available for allocation. SBTC_RELEASESTRPTR Return a pointer to the protocol stack's name and version information string. SBTC_S2ERRNOSTRPTR This function is deprecated and should not used by new code. The error string corresponding to a SANA-II I/O error code. The tag is used both for input and output: in goes the error code (a pointer to an integer), out goes a pointer to the corresponding error string. SBTC_S2WERRNOSTRPTR This function is deprecated and should not used by new code. The error string corresponding to a SANA-II wire error code. The tag is used both for input and output: in goes the error code (a pointer to an integer), out goes a pointer to the corresponding error string. SBTC_SIGEVENTMASK Exec signal mask for asynchronous event notification (see GetSocketEvents()). SBTC_SIGIOMASK This function is deprecated and should not used by new code. Exec signal mask for asynchronous socket events. SBTC_SIGURGMASK This function is deprecated and should not used by new code. Exec signal mask for out-of-band data. SBTC_SYSTEM_STATUS This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. The bsdsocket.library may be opened by any client, yet this does not imply that all the services it supports will be configured as well. To find out whether the TCP/IP stack is operational, you can use use the 'SBTC_SYSTEM_STATUS' tag. The status long word filled in will have the following flags set provided that the associated conditions are true: SBSYSSTAT_Interfaces Network interfaces are available, have IP addresses assigned, are configured and operational. Note that 'network interfaces' does not imply the loopback interface, which is always available and configured. SBSYSSTAT_PTP_Interfaces Point-to-point network interfaces, such as for SLIP or PPP, have IP addresses assigned, are configured and operational. SBSYSSTAT_BCast_Interfaces Broadcast network interfaces, such as Ethernet, have IP addresses assigned, are configured and operational. SBSYSSTAT_Resolver Domain name server addresses are configured. Address resolution is possible. SBSYSSTAT_Routes Routes are configured and operational. IP packets sent will find a way to their destinations. Note such routes will by default be assigned to interfaces that have IP addresses configured, too. SBSYSSTAT_DefaultRoute A default route is configured. SBTC_UDP_CHECKSUM This tag is an extension to the AmiTCP V4 API and cannot be expected to be supported by older "bsdsocket.library" versions. This tag is for querying and changing whether UDP datagram checksums are enabled or not. If enabled, UDP checksums are calculated for outgoing UDP datagrams, and incoming UDP datagrams containing nonzero checksums will have their checksums verified. If disabled, no UDP checksums will be calculated for outgoing datagrams, and no checksums of incoming datagrams will be verified. UDP datagram checksums are enabled by default. Note that this option affects the entire protocol stack and is not limited to the library base you set it with. RESULT Returns 0 on success, and a (positive) index of the failing tag on error. The first tag corresponds to index #1, the second to index #2 and so on. EXAMPLES /* Link the local program's 'errno' variable to the stack's internal 'errno' variable. */ #include #include SocketBaseTags( SBTM_SETVAL(SBTC_ERRNOPTR(sizeof(errno))), &errno, TAG_END); /* Obtain the descriptive text associated with an error number that may have been generated by the stack. */ struct TagItem tags[2]; STRPTR text; int error; /* This query will modify the TagItem list. */ tags[0].ti_Tag = SBTM_GETVAL(SBTC_ERRNOSTRPTR); tags[0].ti_Data = error; tags[1].ti_Tag = TAG_END; SocketBaseTagList(tags); text = (STRPTR)tags[0].ti_Data; /* Disable Ctrl+C checking. */ SocketBaseTags( SBTM_SETVAL(SBTC_BREAKMASK),0, TAG_END); /* Find out how many packet filter channels are available. Note that this option is not supported by all "bsdsocket.library" implementations and should therefore be assumed to return an error or fail to initialize the variable queried. The following example handles this case. */ LONG num_packet_filter_channels; /* Initialize the variable to zero, so that we will always have a meaningful result, even if the library fails to fill it in. */ num_filter_channels = 0; if(SocketBaseTags( SBTM_GETREF(SBTC_NUM_PACKET_FILTER_CHANNELS),&num_filter_channels, TAG_END) != 0) { /* We didn't get what we wanted. Play it safe and reset the number of channels to zero. */ num_filter_channels = 0; } /* Disable ICMP echo message processing, which will cause any attempts to 'ping' this host to fail. */ SocketBaseTags( SBTM_SETVAL(SBTC_ICMP_PROCESS_ECHO),IR_Drop, TAG_END); NOTES The 'SBTC_BREAKMASK' tag code gives you control over the signal mask which is used for testing whether an interrupt signal was received, intended to stop a network operation in progress. Due to how this test is performed, it only takes effect if the operation in progress is currently waiting for something to happen, e.g. more data to arrive or data to become ready for transmission. This means that you cannot expect bsdsocket.library function to respond at all times to the break signal. If there is no reason for the respective function to wait, it will ignore the break signal altogether. Consequently, you may have to perform additional break signal testing in your own application software. SEE ALSO bpf_open(), bpf_close(), bpf_read(), bpf_write(), bpf_set_notify_mask(), bpf_set_interrupt_mask(), bpf_ioctl(), bpf_data_waiting(), GetSocketEvents(), AddRouteTagList(), DeleteRouteTagList(), AddInterfaceTagList(), ConfigureInterfaceTagList(), AddNetMonitorHookTagList(), RemoveNetMonitorHook(). bsdsocket.library/vsyslog bsdsocket.library/vsyslog NAME vsyslog - control system log SYNOPSIS #include #include vsyslog(priority, message, args) D0 A0 A1 void vsyslog(long priority, char *message, va_list args); void syslog(long priority, char *message, ...); FUNCTION The syslog() function writes message to the system message logger. The message is then written to the system console, log files, logged-in users, or forwarded to other machines as appropriate. The message is identical to a printf() format string, except that `%m' is replaced by the current error message. (As denoted by the global variable errno; see strerror().) A trailing newline is added if none is present. The vsyslog() function is an alternate form in which the arguments have already been captured using variable-length argument facilities. The message is tagged with priority. Priorities are encoded as a facility and a level. The facility describes the part of the system generating the message. The level is selected from the following ordered (high to low) list: LOG_EMERG A panic condition. This is normally broadcast to all users. LOG_ALERT A condition that should be corrected immediately, such as a corrupted system database. LOG_CRIT Critical conditions, e.g. hard device errors. LOG_ERR Errors. LOG_WARNING Warning messages. LOG_NOTICE Conditions that are not error conditions, but should possibly be handled specially. LOG_INFO Informational messages. LOG_DEBUG Messages that contain information normally of use only when debugging a program. NOTES This function should not be called from interrupt code. bsdsocket.library/WaitSelect bsdsocket.library/WaitSelect NAME WaitSelect - synchronous I/O multiplexing SYNOPSIS #include #include #include n = WaitSelect(nfds, readfds, writefds, exceptfds, timeout, signals) D0 D0 A0 A1 A2 A3 D1 long Waitselect(long nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout, ULONG *signals); FD_SET(fd, &fdset); FD_CLR(fd, &fdset); FD_ISSET(fd, &fdset); FD_ZERO(&fdset); FUNCTION WaitSelect() examines the I/O descriptor sets whose addresses are passed in readfds, writefds, and exceptfds to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. The first nfds descriptors are checked in each set; i.e., the descriptors from 0 through nfds-1 in the descriptor sets are examined. On return, WaitSelect() replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. WaitSelect() returns the total number of ready descriptors in all the sets. The descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such descriptor sets: FD_ZERO(&fdsetx) initializes a descriptor set fdset to the null set. FD_SET(fd, &fdset) includes a particular descriptor fd in fdset. FD_CLR(fd, &fdset) removes fd from fdset. FD_ISSET(fd, &fdset) is nonzero if fd is a member of fdset, zero otherwise. The behavior of these macros is undefined if a descriptor value is less than zero or greater than or equal to FD_SETSIZE, which is normally at least equal to the maximum number of descriptors supported by the system. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To affect a poll, the timeout argument should not be NULL, pointing to a zero-valued timeval structure. Any of readfds, writefds, and exceptfds may be given as NULL pointers if no descriptors are of interest. NOTES WaitSelect() corresponds to select(). It will block until the wait criteria could be satisfied (a socket has become ready), the timeout has elapsed or a signal was received before any of the other two events could occur. By default one of these signals is the standard break signal which can be configured using the SocketBaseTagList() 'SBTC_BREAKMASK' tag. To specify user signals that should cause WaitSelect() to return immediately, use the 'signals' parameter. The long word pointed to should contain a signal mask. If WaitSelect() is called with a timeout of 0 seconds and 0 microseconds, it will effectively "poll" the current state of the files/sockets specified and return without waiting for any of them to become ready. Reception of the standard break signal (e.g. via Ctrl+C) will cause WaitSelect() to return -1 and set the error code to EINTR. Additionally, the standard break signal will be posted. This means that the signal will still be set when WaitSelect() returns, and can be tested. If -1 is returned, the contents of the user signal mask pointed to by the 'signals' parameter will be undefined. Reception of a user signal with no socket ready will cause WaitSelect() to stop and to return 0. If WaitSelect() returns a value of 0 or greater, the current Task's received signal mask will be updated according to which bits were set in the user signal mask pointed to by the 'signals' parameter. If the received signal mask and the user signal mask have the same bits set, then these bits will remain set in the user signal mask and the received signal mask will have them cleared. If a user signal mask bit is set, and the corresponding received signal mask bit is clear, then the user signal mask bit will be cleared. Passing a NULL for the 'signals' parameter will cause WaitSelect() to operate like select(), i.e. the function will return only if the timeout has elapsed, a socket has become ready or an break signal was received (e.g. via Ctrl+C). The same is true if the long word pointed to by the 'signals' parameter is zero. The timeout value must be sound. This means that the number of microseconds must be smaller than 1000000 and the number of seconds must not be larger than 100000000. If you want the WaitSelect() function to wait indefinitely, do not set up a very long wait interval and use it repeatedly. Use a NULL pointer for for the timeout parameter instead. The 'nfds' parameter may be truncated if it covers more sockets than are currently in use. This has the side-effect of filling in only as many socket bits in the fd_set parameters you provide as are currently in use, and not as many as you asked for. You should therefore take care not to ask for more sockets to be checked than you know are still in use, or the results produced by WaitSelect() will be ambiguous. The break signal mask and the user signal mask pointed to by the 'signals' parameter should not share common signal bits. Otherwise the information returned in the data pointed to by the 'signals' parameter, or the break signal handling itself, will be ambiguous. For example, the bits common to the break signal mask and the user signal mask will be attributed to the user signals, and when WaitSelect() returns the break signal mask will not be posted. Owing to the use of the 'fd_set' data structure, WaitSelect() may need to use several thousands bytes of stack space for each invocation, and might also allocate additional memory. The extra memory allocation may have a negative impact on performance if you expect the function to do its job quickly. The stack size requirements of at least 4000 bytes may need care and attention in your software: do not shave the stack too closely. RESULT WaitSelect() returns the number of ready descriptors that are contained in the descriptor sets, or -1 if an error occurred. If the time limit expires, WaitSelect() returns 0. If WaitSelect() returns with an error, including one due to an interrupted call, the descriptor sets will be unmodified. ERRORS An error return from WaitSelect() indicates: [EBADF] One of the descriptor sets specified an invalid descriptor. [EINTR] A signal was delivered before the time limit expired and before any of the selected events occurred. [EINVAL] The specified time limit is invalid. One of its components is negative or too large. SEE ALSO accept(), connect(), getdtablesize(), recv(), send() BUGS Although the provision of getdtablesize() was intended to allow user programs to be written independent of the kernel limit on the number of open files, the dimension of a sufficiently large bit field for select remains a problem. The default size FD_SETSIZE (currently 256) is somewhat larger than the current kernel limit to the number of open files. However, in order to accommodate programs which might potentially use a larger number of open files with select, it is possible to increase this size within a program by providing a larger definition of FD_SETSIZE before the inclusion of . WaitSelect() should probably return the time remaining from the original timeout, if any, by modifying the time value in place. This may be implemented in future versions of the system. Thus, it is unwise to assume that the timeout value will be unmodified by the WaitSelect() call. WaitSelect() may ignore the break signal altogether if a zero length timeout is given, or sockets are ready at the time the function is entered. This behaviour was changed in bsdsocket.library V4.289, which will always make sure that the break signal is tested and acted upon -- note that no other AmiTCP-alike Amiga TCP/IP stack may check the break signal under these circumstances, which means that if you need to know whether a break signal was pending at the time WaitSelect() was called, you may have to do it yourself.