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.