socket

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int socket (
int family,
int type,
int protocol
);


Function Description

socket() creates an endpoint for communication and returns a descriptor. The family parameter specifies a communications domain in which communication will take place; this selects the protocol family that should be used. The protocol family is generally the same as the address family for the addresses supplied in later operations on the socket. These families are defined in the include file <trsocket.h>. If protocol has been specified, but no exact match for the tuplet family, type, and protocol is found, then the first entry containing the specified family and type, with zero for the protocol will be used. The socket has the indicated type, which specifies the communication semantics.

Currently defined types are:

  • SOCK_STREAM
  • SOCK_DGRAM
  • SOCK_RAW

A SOCK_STREAM type provides sequenced, reliable, two-way connection-based byte streams. An out-of-band data transmission mechanism is supported. A SOCK_DGRAM socket supports datagrams (connectionless, unreliable messages of a fixed (typically small) maximum length); a SOCK_DGRAM user is required to read an entire packet with each recv() call or variation of recv() call, otherwise an error code of TM_EMSGSIZE is returned. 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, multiple 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. If the caller specifies a protocol, then it will be packaged into a socket level option request and sent to the underlying protocol layers. Sockets of type SOCK_STREAM are full-duplex byte streams. 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 connect() on the client side. On the server side, the server must call listen() and then accept(). Once connected, data may be transferred using recv() and send() calls or some variant of the send() and recv() calls. When a session has been completed, a tfClose() of the socket should be performed. The communications protocols used to implement a SOCK_STREAM ensure 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 TM_SOCKET_ERROR return value and with TM_ETIMEDOUT as the specific socket error. The TCP protocol optionally keeps sockets "warm" by forcing transmissions roughly every two hours in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise idle connection for an extended period (for instance 5 minutes). SOCK_DGRAM or SOCK_RAW sockets allow datagrams to be sent to correspondents named in sendto() calls. Datagrams are generally received with recvfrom() which returns the next datagram with its return address. The operation of sockets is controlled by socket level options. These options are defined in the file <trsocket.h>. setsockopt() and getsockopt() are used to set and get options, respectively.


Parameters

  • family
    The protocol family to use for this socket. PF_INET and PF_INET6 are supported.
  • type
    The type of socket. SOCK_GRAM, SOCK_STREAM, and SOCK_RAW are supported.
  • protocol
    The name of the option to set. IPPROTO_UDP, IPPROTO_TCP, IPPROTO_SCTP, IPPROTO_ICMP, IPPROTO_IGMP, and IPPROTO_ICMPV6 are supported.


Family Type Protocol Actual Protocol
PF_INET SOCK_DGRAM IPPROTO_UDP UDP/IPv4
PF_INET SOCK_STREAM IPPROTO_TCP TCP/IPv4
PF_INET SOCK_STREAM IPPROTO_SCTP SCTP/IPv4
PF_INET SOCK_RAW IPPROTO_ICMP ICMP/IPv4
PF_INET SOCK_RAW IPPROTO_IGMP IGMP/IPv4
PF_INET6 SOCK_DGRAM IPPROTO_UDP UDP/IPv6
PF_INET6 SOCK_STREAM IPPROTO_TCP TCP/IPv6
PF_INET6 SOCK_RAW IPPROTO_ICMPV6 ICMP/IPv6


Returns

  • >= 0
    New socket descriptor
  • TM_SOCKET_ERROR
    Failure


Note Note: TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself.

To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).


Possible socket errors

  • TM_EMFILE
    No more sockets are available.
  • TM_ENOBUFS
    Insufficient memory to complete the operation.
  • TM_EPROTONOSUPPORT
    The specified protocol is not supported within this family.
  • TM_EPFNOSUPPORT
    The protocol family is not supported.


Table of Contents >> Programmer's Reference