TCP/IP Sockets functionality unit This document describes the SOCKETS unit for Free Pascal. it was written for linux by Michael Van Canneyt, and ported to Windows by Florian Klaempfl. Type of socket: stream (connection) type socket (TCP) Type of socket: datagram (conn.less) socket (UDP) Type of socket: raw socket Type of socket: reliably-delivered message Type of socket: sequential packet socket Type of socket: Packet Address family Not specified Address family Unix domain sockets Address family Internet IP Protocol Address family Amateur Radio AX.25 Address family Novell IPX Address family Appletalk DDP Address family Amateur radio NetROM Address family Multiprotocol bridge Address family Reserved for Werner's ATM Address family Reserved for X.25 project Address family IP version 6 Address family Maximum value Address family: ATM PVCs Address family: Amateur Radio X.25 PLP Address family: Reserved for 802.2LLC project Address family: Security callback pseudo AF Address family: PF_KEY key management API Address family: ? Address family: Packet family Address family: Ash Address family: Acorn Econet Address family: ATM SVCs Address family: IRDA sockets Address family: PPPoX sockets Address family: Wanpipe API Sockets Address family: Linux LLC Address family: TIPC sockets Address family: Bluetooth sockets Protocol family: Unspecified Protocol family: Internet IP Protocol Protocol family: Amateur Radio AX.25 Protocol family: Novell IPX Protocol family: Appletalk DDP Protocol family: Unix domain sockets Protocol family:Amateur radio NetROM Protocol family: Multiprotocol bridge Protocol family: Reserved for Werner's ATM Protocol family: Reserved for X.25 project Protocol family: IP version 6 Protocol family: Maximum value Protocol family: ATM PVCs Protocol family: Amateur Radio X.25 PLP Protocol family: Reserved for 802.2LLC project Protocol family: Security callback pseudo PF Protocol family: ? Protocol family: Packet family Protocol family: Ash Protocol family: Acorn Econet Protocol family: ATM SVCs Protocol family: IRDA sockets Protocol family: PPPoX sockets Protocol family: Wanpipe API Sockets Protocol family: Linux LLC Protocol family: TIPC sockets Protocol family: Bluetooth sockets Maximum queue length specifiable by listen. Alias for MSG_FIN Invalid socket return value (for kylix compatibility) Socket error indication (for kylix compatibility) Alias for pin_addr Protocol family for unix socket Filename for unix socket file Access forbidden error Error code ? Wrong message size error No buffer space available error Not connected error File descriptor is not a socket error Protocol not supported error Operation would block error General socket adress record sockaddr is used to store a general socket addres for the , and calls. Address family Addres data Address family Addres data Socket family Socket port Socket address Padding bytes Unix socket address record. sockaddr_un is used to store a UNIX socket addres for the , and calls. Address family File name Pointer to sockaddr_un type. Alias for sockaddr_un Internet socket address record sockaddr_in is used to store a INET socket addres for the , and calls. Pointer to sockaddr_in Alias for sockaddr_in Internet socket family Internet socket port Internet socket host address Padding bytes Address family Port number IP address Pad data. Do not use. Type returned by the call. Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Addresss family: Linux SNA project Address family: Reserved for DECnet project. Address family: ? Address family: ? Address family: ? Address family: Alias to emulate 4.4BSD. Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: ? Address family: key management API. Address family: ? Address family: ? Address family: ? Address family: ? Maximum socket address length for call. Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: Linux SNA project Protocol Family: DECNET project Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol Family: ? Protocol family: Key management API Protocol Family: ? Protocol Family: ? Protocol Family: ? Socket option level: Socket level Socket option level: debug Socket option: Reuse address Socket option: Type Socket option: Error Socket option: Don't route Socket option: Broadcast Socket option: Send buffer Socket option: receive buffer Socket option: keep alive Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Socket option: ? Shutdown read part of full duplex socket Shutdown write part of full duplex socket Shutdown read and write part of full duplex socket Address family type Protocol family: Unix socket Protocol family: Unix socket (alias) Address family: Unix socket Address family: Unix socket (alias) Receive flags: receive out-of-band data. Receive flags: peek at data, don't remove from buffer. Send flags: don't use gateway Receive flags: ? Receive flags: Control Data was discarded (buffer too small) Receive flags: ? Receive flags: packet Data was discarded (buffer too small) Receive flags: Non-blocking operation request. Receive flags: End of record Receive flags: Wait till operation completed. Receive flags: ? Receive flags: ? Send flags: Conform connection Receive flags: ? Receive flags: ? Receive flags: Suppress SIG_PIPE signal. Receive flags: ? Input socket in socket pair. Output socket in socket pair General inet socket address. Actual address General socket address: Address family General socket address: Address data Pointer to Pointer to Alias for Pointer to Record for IPV6 socket address. Address family Port Flow information. IPV6 address Alias for Pointer to Pointer to linger type. Record used in setsockopt This record is used in the call to specify linger options. Linger on or off Time to linger Alias for linger General purpose IPV6 address Record used to describe a general IPV6 address. Address field using unsigned 8 bit elements Address field using unsigned 16 bit elements Address field using unsigned 32 bit elements Address field using signed 8 bit elements Address field using signed 8 bit elements Address field using signed 16 bit elements Address field using signed 32 bit elements Alias for in6_addr type. Pointer to in6_addr type. Alias for sockaddr_in6 Pointer to sockaddr_in6 type Alias for easy kylix porting Array of sockets, used in call. Contains the error code for the last socket operation. SocketError contains the error code for the last socket operation. It can be examined to return the last socket error. Closes a socket handle. CloseSocket closes a socket handle. It returns 0 if the socket was closed succesfully, -1 if it failed. On error, -1 is returned. Send data through an unconnected socket to an address. fpSendTo sends data from buffer Msg with length len through socket S with options Flags. The data is sent to address tox, which has length toLen On error, -1 is returned. Receive data from an unconnected socket fpRecvFrom receives data in buffer Buf with maximum length Len from socket S. Receipt is controlled by options in Flags. The location pointed to by from will be filled with the address from the sender, and it's length will be stored in fromlen. The function returns the number of bytes received, or -1 on error. AddrLen. On error, -1 is returned. Accept a connection from a socket.

Accept accepts a connection from a socket S, which was listening for a connection. If a connection is accepted, a file descriptor is returned (positive number). On error -1 is returned. The returned socket may NOT be used to accept more connections. The original socket remains open.

The Accept call fills the address of the connecting entity in Addrx, and sets its length in Addrlen. Addrx should be pointing to enough space, and Addrlen should be set to the amount of space available, prior to the call.

On error, -1 is returned, and errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The descriptor is not a socket.
SYS_EOPNOTSUPP
The socket type doesn't support the Listen operation.
Addr points outside your address space.
The requested operation would block the process.
Accept a connection from a socket (deprecated).

Accept accepts a connection from a socket Sock, which was listening for a connection. If a connection is accepted, a file descriptor is returned. On error -1 is returned. The returned socket may NOT be used to accept more connections. The original socket remains open.

The Accept call fills the address of the connecting entity in Addr, and sets its length in Addrlen. Addr should be pointing to enough space, and Addrlen should be set to the amount of space available, prior to the call.

The alternate forms of the command, with the Text or File parameters are equivalent to subsequently calling the regular function and the or functions. These functions return True if successful, False otherwise.

On error, -1 is returned, and errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The descriptor is not a socket.
SYS_EOPNOTSUPP
The socket type doesn't support the Listen operation.
Addr points outside your address space.
The requested operation would block the process.
Bind a socket to an address.

fpBind binds the socket s to address Addrx. Addrx has length Addrlen. The function returns 0 if the call was succesful, -1 if not.

Errors are returned in SocketError and include the following:

The socket descriptor is invalid.
The socket is already bound to an address,
Address is protected and you don't have permission to open it.

More errors can be found in the Unix man pages.

Alias for fpBind.

Bind is an alias for which binds to either a socket struct (Addr) or a string indicating a unix socket file (unix socket).

This function is deprecated, use fpBind instead.

Open a connection to a server socket.

fpConnect uses the socket s to open a connection to a peer, whose address is described by Name. NameLen contains the length of the address. The type of Name depends on the kind of connection you are trying to make, but is generally one of TSockAddr or TUnixSockAddr.

The fpConnect function returns zero if the call was successfull, -1 in case of error.

On error, -1 is returned and errors are reported in SocketError.
Open a connection to a server socket (deprecated).

Connect opens a connection to a peer, whose address is described by Addr. AddrLen contains the length of the address. The type of Addr depends on the kind of connection you're trying to make, but is generally one of TSockAddr or TUnixSockAddr.

The forms of the command with the Text or File arguments are equivalent to subsequently calling the regular Connect function and the or functions. These functions return True if successfull, False otherwise.

The Connect function returns a file descriptor if the call was successfull, -1 in case of error.

On error, -1 is returned and errors are reported in SocketError.
Return the name (address) of the connected peer.

fpGetPeerName returns the name of the entity connected to the specified socket S. The Socket must be connected for this call to work.

Name should point to enough space to store the name, the amount of space pointed to should be set in Namelen. When the function returns succesfully, Name will be filled with the name, and Name will be set to the length of Name.

Errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The system doesn't have enough buffers to perform the operation.
The descriptor is not a socket.
Addr points outside your address space.
The socket isn't connected.
Return name of socket. fpGetSockName returns the current name of the specified socket S. Name should point to enough space to store the name, the amount of space pointed to should be set in Namelen. When the function returns succesfully, Name will be filled with the name, and Namelen will be set to the length of Name.

Errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The system doesn't have enough buffers to perform the operation.
The descriptor is not a socket.
Addr points outside your address space.
Get current socket options

fpGetSockOpt gets the connection option optname, for socket S. The socket may be obtained from different levels, indicated by Level, which can be one of the following:

SOL_SOCKET
From the socket itself.
XXX
set Level to XXX, the protocol number of the protocol which should interpret the option.

The options are stored in the memory location pointed to by optval. optlen should point to the initial length of optval, and on return will contain the actual length of the stored data.

On success, 0 is returned. On Error, -1 is returned.

Errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The descriptor is not a socket.
OptVal points outside your address space.
Listen for connections on a socket.

fpListen listens for up to backlog connections from socket S. The socket S must be of type SOCK_STREAM or Sock_SEQPACKET.

The function returns 0 if a connection was accepted, -1 if an error occurred.

Errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The descriptor is not a socket.
SYS_EOPNOTSUPP
The socket type doesn't support the Listen operation.
Receive data on socket

fpRecv reads at most len bytes from socket S into address buf. The socket must be in a connected state. Flags can be one of the following:

1
Process out-of band data.
4
Bypass routing, use a direct interface.
??
Wait for full request or report an error.

The functions returns the number of bytes actually read from the socket, or -1 if a detectable error occurred.

Errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The socket isn't connected.
The descriptor is not a socket.
The address is outside your address space.
The message cannot be sent atomically.
The requested operation would block the process.
The system doesn't have enough free buffers available.
Send data through socket

fpSend sends Len bytes starting from address Msg to socket S. S must be in a connected state. Options can be passed in Flags.

The function returns the number of bytes sent, or -1 if a detectable error occurred.

Flags can be one of the following:

1
Process out-of band data.
4
Bypass routing, use a direct interface.

Errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The descriptor is not a socket.
The address is outside your address space.
The message cannot be sent atomically.
The requested operation would block the process.
The system doesn't have enough free buffers available.
Set socket options.

fpSetSockOpt sets the connection options for socket S. The socket may be manipulated at different levels, indicated by Level, which can be one of the following:

SOL_SOCKET
To manipulate the socket itself.
XXX
set Level to XXX, the protocol number of the protocol which should interprete the option.

The actual option is stored in a buffer pointed to by optval, with length optlen.

For more information on this call, refer to the unix manual page setsockopt

Errors are reported in SocketError, and include the following:

The socket descriptor is invalid.
The descriptor is not a socket.
OptVal points outside your address space.
Close one end of full duplex connection.

fpShutDown closes one end of a full duplex socket connection, described by S. The parameter How determines how the connection will be shut down, and can be one of the following:

0
Further receives are disallowed.
1
Further sends are disallowed.
2
Sending nor receiving are allowed.

On succes, the function returns 0, on error -1 is returned.

SocketError is used to report errors, and includes the following:

The socket descriptor is invalid.
The socket isn't connected.
The descriptor is not a socket.
Convert socket to untyped file descriptors Sock2File transforms a socket Sock into 2 Pascal file descriptors of type File, one for reading from the socket (SockIn), one for writing to the socket (SockOut). None. Convert socket to text file descriptors Sock2Text transforms a socket Sock into 2 Pascal file descriptors of type Text, one for reading from the socket (SockIn), one for writing to the socket (SockOut). None. Create new socket

fpSocket creates a new socket in domain Domain, from type xType using protocol Protocol. The Domain, Socket type and Protocol can be specified using predefined constants (see the section on constants for available constants) If succesfull, the function returns a socket descriptor, which can be passed to a subsequent call. If unsuccesfull, the function returns -1.

for an example, see .

Errors are returned in SocketError, and include the follwing:

The protocol type or the specified protocol is not supported within this domain.
The per-process descriptor table is full.
SYS_ENFILE
The system file table is full.
Permission to create a socket of the specified type and/or protocol is denied.
Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed.
Create socket pair. fpSocketPair creates 2 sockets in domain D, from type xType and using protocol Protocol. The pair is returned in sv, and they are indistinguishable. The function returns -1 upon error and 0 upon success. Errors are reported in SocketError, and are the same as in Convert path to Str2UnixSockAddr transforms a Unix socket address in a string to a TUnixSockAddr structure which can be passed to the call. None. Convert long integer from host ordered to network ordered htonl makes sure that the bytes in host are ordered in the correct way for sending over the network and returns the correctly ordered result. Convert short integer from host ordered to network ordered htons makes sure that the bytes in host are ordered in the correct way for sending over the network and returns the correctly ordered result. Convert long integer from network ordered to host ordered ntohs makes sure that the bytes in Net, received from the network, are ordered in the correct way for handling by the host machinen, and returns the correctly ordered result. Convert short integer from network ordered to host ordered ntohs makes sure that the bytes in Net, received from the network, are ordered in the correct way for handling by the host machinen, and returns the correctly ordered result. Basic Unix types Alias for in_addr record type. Pointer to in_addr record. Alias for in_addr record type. Array with same length as in_addr record in_addrbytes is used to typecast a record to an array of bytes. Alias for TSockAddr record type. Convert a network address to a string. NetAddrToStr converts the network address in Entry to a string representation in human-readable form (a dotted quad). Convert a host address to a string.

HostAddrToStr converts the host address in Entry to a string representation in human-readable form (a dotted quad).

Basically, it is the same as , but with the bytes in correct order.

Convert a string to a host address. StrToHostAddr converts the string representation in IP to a host address and returns the host address. On error, the host address is filled with zeroes. Convert a string to a network address. StrToNetAddr converts the string representation in IP to a network address and returns the network address. On error, the network address is filled with zeroes. Convert a host address to a network address HostToNet converts a host address to a network address. It takes care of endianness of the host machine. The address can be specified as a dotted quad or as a longint. None. Convert a network address to a host address. NetToHost converts a network address to a host address. It takes care of endianness of the host machine. The address can be specified as a dotted quad or as a longint. None. Convert a host port number to a network port number ShortHostToNet converts a host port number to a network port number. It takes care of endianness of the host machine. None. Convert a network port number to a host port number ShortNetToHost converts a network port number to a host port number. It takes care of endianness of the host machine. None. Convert a IPV6 host address to a string representation.

HostAddrToStr6 converts the IPV6 host address in Entry to a string representation in human-readable form.

Basically, it is the same as , but with the bytes in correct order.

Convert a string to a IPV6 host address. StrToHostAddr6 converts the string representation in IP to a IPV6 host address and returns the host address. On error, the address is filled with zeroes. Convert a IPV6 network address to a string.

NetAddrToStr6 converts the IPV6 network address in Entry to a string representation in human-readable form.

Basically, it is the same as , but with the bytes in correct order.

Convert a string to a IPV6 network address StrToNetAddr6 converts the string representation in IP to a IPV6 network address and returns the network address. On error, the address is filled with zeroes. Constant indicating invalid (no) network address. Constant indicating invalid (no) network address. Constant indicating invalid (no) IPV6 network address. Constant indicating invalid (no) IPV6 network address. Unix types Dummy protocol for TCP. IPv6 Hop-by-Hop options. Internet Control Message Protocol. Internet Group Management Protocol. IPIP tunnels (older KA9Q tunnels use 94). Transmission Control Protocol. Exterior Gateway Protocol. PUP protocol. User Datagram Protocol. XNS IDP protocol. SO Transport Protocol Class 4. IPv6 header. IPv6 routing header. IPv6 fragmentation header. Reservation Protocol. General Routing Encapsulation. encapsulating security payload. authentication header. ICMPv6. IPv6 no next header. IPv6 destination options. Multicast Transport Protocol. Encapsulation Header. Protocol Independent Multicast. Compression Header Protocol. Stream Control Transmission Protocol. Raw IP packets. Maximum value for IPPROTO options IP per-packet options. Header is included with data. IP type of service and precedence. IP time to live. Receive all IP options w/datagram. Set/get IP per-packet options. Receive IP options for response. set/get IP multicast i/f set/get IP multicast ttl set/get IP multicast loopback add an IP group membership drop an IP group membership unblock data from source block data from source join source group leave source group Undocumented ? join any-source group block from given group unblock from given group leave any-source group join source-spec gruoup leave source-spec group Undocumented ? Undocumented ? Undocumented ? Undocumented ? Undocumented ? Undocumented ? Undocumented ? Undocumented ? Undocumented ? Undocumented ? Undocumented ? Never send DF frames. Use per route hints. Always DF. Undocumented ? Undocumented ? Undocumented ? Maximum group memberships for multicast messages Change the IPV6 address into a different address family. Deprecated Change delivery options for incoming IPV6 datagrams Deliver hop option control messages Deliver destination option control messages Deliver routing header control messages Undocumented Getsockopt option ? Undocumented Getsockopt option ? Undocumented Getsockopt option ? Deliver an integer containing the HOP count Undocumented Getsockopt option ? sendmsg: set next hop for IPV6 datagram GetSockOpt/SetSockopt: Deliver authentication header messages GetSockOpt/SetSockopt: Get/Set unicast hop limit GetSockOpt/SetSockopt: Get/Set device for multicast packages on the socket. GetSockOpt/SetSockopt: Get/Set the multicast hop limit. GetSockOpt/SetSockopt: Control whether socket sees multicast packages that it has sent itself GetSockOpt/SetSockopt: Control membership (join group) in multicast groups GetSockOpt/SetSockopt: Control membership (leave group)in multicast groups GetSockOpt/SetSockopt: Get/Set Pass all forwarded packets containing router alert option GetSockOpt/SetSockopt: Get/Set Control path MTU Discovery on the socket GetSockOpt/SetSockopt: Get/Set the MTU for the socket GetSockOpt/SetSockopt: Control receiving of asynchroneous error options GetSockOpt/SetSockopt: Handle IPV6 connections only Undocumented Getsockopt option ? Undocumented Getsockopt option ? Undocumented Getsockopt option ? Undocumented Getsockopt option ? Undocumented Getsockopt option ? Undocumented Getsockopt option ? Undocumented Getsockopt option ? Undocumented Getsockopt option ? Never send DF frames. Use per route hints. Always DF. Socket level values for IPv6: IPV6 Socket level values for IPv6: ICMPV6 Hop doesn't need to be neighbour. Hop must be a neighbour. IPv6 Routing header type 0. A bitmask matching any IP address on the local machine. A bitmask matching no valid IP address Address as bytes Internet socket family Internet socket port Internet socket host address Padding IPV6 socket address as bytes IPV6 socket address as words IPV6 socket address as cardinals IPV6 socket address as shortints IPV6 socket address as shortints IPV6 socket address as smallints IPV6 socket address as longints Alias : operation interrupted Alias: bad file descriptor Alias: an error occurred Alias: Invalid value specified Type to specify socket length in fpBind and fpConnect The actual type of TSockLen depends on the platform. Get/Set No delay flag: disable Nagle algorithm Get/Set Maximum segment size Get/Set CORK algorithm: Send only complete packets Get/Set inactivity interval between KEEPALIVE transmissions. Get/Set retry interval for unacknowledged KEEPALIVE transmissions. Get/Set retry count for unacknowledged KEEPALIVE transmissions. Get/Set number of SYN packets to send before givin up on connection establishment Get/Set Linger2 flag Get/Set deferred accept on server socket Get/Set maximum packet size Get TCP connection information (linux only) Get/Set quik ACK packet option. Get/set the congestion-control algorithm for this socket Get/Set TCP MD5 signature option Get/Set UDP CORK algorithm on datagram sockets Get/Set UDP encapsulation flag for IPSec datagram sockets ? Undocumented datagram option, IPSec related ? Undocumented datagram option, IPSec related ? Undocumented datagram option, IPSec related