Socket operations

0x00 Socket Create

This function sets up a new socket and returns a handle for its future use. Only a limited number of sockets can be opened simultaneously.

XY+	Length	On entry	On exit
4	4	Communications domain, 2 for PF_INET	socket number created or -1 on failure
8	4	Socket type: 1=stream 2=datagram 3=raw
12	4	Protocol or zero for default for the socket type

0x01 Socket Bind

Bind a socket to a specific local address.

XY+	Length	On entry	On exit
4	4	socket	-1 if the bind fails
8	4	Pointer to socket address to bind to
12	4	Size of socket address, usually 16

Socket address

sa+	Length	On entry
0	1	Size of socket address, usually 16
1	1	Address family, 2 for AF_INET
2	2	Port number
4	4	IPv4 address
8	4	Zero
12	4	Zero

Note that the size of the socket address structure is used twice, once in the structure itself, and also as the third parameter at YX+12.

0x02 Socket Listen

Switch a socket into listening for incoming connection attempts. Only sockets opened and configured to tbe stream based sockets can be set to listen, datagram and raw sockets are connectionless and cannot be set to listen.

XY+	Length	On entry	On exit
4	4	socket	-1 if the call fails
8	4	Backlog of unaccepted connections to allow before rejecting

0x03 Socket Accept

XY+	Length	On entry	On exit
4	4	socket	-1 if the bind fails
8	4	Pointer to socket address to bind to
12	4	pointer to an integer describing the size of socket address (usually 16)

Note: XY+12 in the original documentation mentions this is a pointer, but in other calls it's an actual value. This needs clarifying.

0x04 Socket Connect

Accept an incoming connection on an existing socket. If there are no pending incoming connections, this call will block until there is one. On accepting, the address details of the remote computer will be filled in at the block pointed to by YX+8.

XY+	Length	On entry	On exit
4	4	socket	-1 if the connect fails
8	4	Pointer to socket address to bind to
12	4	size of socket address (usually 16)

0x05 Socket Receive

Read data from the given socket. This function attempts to read data or waits until some is ready.

It is possible that zero bytes are returned, probably indicating that the remote computer has disconnected.

XY+	Length	On entry	On exit
4	4	socket	-1 on failure, otherwise number of bytes received
8	4	Pointer to data buffer to receive into
12	4	Buffer size
16	4	Flags, usually 0

0x08 Socket Send

Send out data on the given socket. For raw and datagram style sockets the message length must fit within one packet otherwise the request will be rejected, for stream style sockets as much as the message as possible will be queued and sent subject to available memory.

XY+	Length	On entry	On exit
4	4	socket	-1 on failure, otherwise number of bytes sent
8	4	Pointer to data buffer to send
12	4	Buffer size
16	4	Flags, usually 0

0x0B Socket Shutdown

Shutdown part of a socket. This allows a socket to be partially shut where the TCP/IP stack supports this. Caution should be taken as this does not actually close the socket, so does not free up any of the resources associated with the socket - see details of Close for how to do this.

XY+	Length	On entry	On exit
4	4	socket	-1 on failure
8	4	Direction to shut 0=receive side 1=transmit side 2=both sides
12	4	Buffer size
16	4	Flags, usually 0

0x10 Socket Close

Close a socket. As there are fixed number of sockets available it is important to remember to close sockets once any transactions are complete.

XY+	Length	On entry	On exit
4	4	socket	-1 on failure

Unsupported actions

The following actions are defined but are not supported. Using them will return an error.

Action	Description
0x06	Socket Receive From
0x07	Socket Receive Message
0x09	Socket Send to
0x0A	Socket Send Message
0x0C	Socket Set Socket Option
0x0D	Socket Get Socket Option
0x0E	Socket Get Peer Name
0x0F	Socket Get Socket Name
0x11	Socket Select
0x12	Socket Ioctl
0x13	Socket Read
0x14	Socket Write
0x15	Socket Stat
0x16	Socket Readv
0x17	Socket Writev

Last modified October 6, 2021: Move BBC content into subdirectory to allow more bbc content (23080e8)