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 Socket domain: Not specified Socket domain: Unix domain sockets Socket domain: Internet IP Protocol Socket domain: Amateur Radio AX.25 Socket domain: Novell IPX Socket domain: Appletalk DDP Socket domain: Amateur radio NetROM Socket domain: Multiprotocol bridge Socket domain: Reserved for Werner's ATM Socket domain: Reserved for X.25 project Socket domain: IP version 6 Socket domain: Maximum value 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 General socket adress record TUnixSockAddr is used to store a general socket addres for the , and calls. Address family Addres data Unix socket address record. TUnixSockAddr is used to store a UNIX socket addres for the , and calls. Address family File name Internet socket address record TUnixSockAddr is used to store a INET socket addres for the , and calls. 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 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. Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call Alias for the call 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. SendTo sends data from buffer Buf with length Buflen through socket Sock with options Flags. The data is sent to address Addr, which has length AddrLen On error, -1 is returned. Receive data from an unconnected socket RecvFrom receives data in buffer Buf with maximum length BufLen from socket Sock. Receipt is controlled by options in Flags. Addr will be filled with the address from the sender, and will have length The function returns the number of bytes received, or -1 on error. AddrLen. On error, -1 is returned. Accept a connection from a socket.

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

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

Bind binds the socket Sock to address Addr. Addr has length Addrlen. The function returns True if the call was succesful, False if not.

The form of the Bind command with the is equivalent to subsequently calling and the regular Bind function. The function returns True if successfull, False otherwise.

Errors are returned in SocketError and include the following:

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

More arrors can be found in the Unix man pages.

Open a connection to a server socket.

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.

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

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

Errors are reported in SocketError, and include the following:

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

Errors are reported in SocketError, and include the following:

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

GetSocketOptions gets the connection options for socket Sock. 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 interprete the option.

For more information on this call, refer to the unix manual page \seem{getsockopt}{2}.

Errors are reported in SocketError, and include the following:

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

Listen listens for up to MaxConnect connections from socket Sock. The socket Sock must be of type SOCK_STREAM or Sock_SEQPACKET.

The function returns True if a connection was accepted, False if an error occurred.

Errors are reported in SocketError, and include the following:

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

Recv reads at most Addrlen bytes from socket Sock into address Addr. 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:

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

Send sends AddrLen bytes starting from address Addr to socket Sock. Sock must be in a connected state. 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:

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

SetSocketOptions sets the connection options for socket Sock. 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.

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

Errors are reported in SocketError, and include the following:

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

ShutDown closes one end of a full duplex socket connection, described by Sock. 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:

SYS_EBADF
The socket descriptor is invalid.
SYS_ENOTCONN
The socket isn't connected.
SYS_ENOTSOCK
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

Socket creates a new socket in domain Domain, from type SocketType 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:

SYS_EPROTONOSUPPORT
The protocol type or the specified protocol is not supported within this domain.
SYS_EMFILE
The per-process descriptor table is full.
SYS_ENFILE
The system file table is full.
SYS_EACCESS
Permission to create a socket of the specified type and/or protocol is denied.
SYS_ENOBUFS
Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed.
 , \seem{socket}{2} Create socket pair SocketPair creates 2 sockets in domain Domain, from type SocketType and using protocol Protocol. The pair is returned in Pair, 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.