# Sockets

This implements the Forth part of the socket I/O interface.
As with the file I/O device, the socket words are a thin
wrapper over the standard Unix socket functions. This means
that it is fairly low level.

~~~
:socket:operation
  DEVICE:SOCKET io:scan-for dup n:negative?
  [ drop 'Error:_socket_device_not_found s:put nl
         'See_https://retroforth.org/support/2022.1/SOCKETS.md
         s:put nl
         'for_instructions_on_enabling_sockets. s:put nl ] if;
  io:invoke ;
~~~

`socket:gethostbyname` gets the host IP in dottode notation. Provide
an address to hold the dotted notation and a string containing the
host name.

~~~
:socket:gethostbyname (:as-)    #0 socket:operation ;
~~~

`socket:create` creates a new socket. It does not take any
parameters, and returns the socket id.

~~~
:socket:create        (:-n)     #1 socket:operation ;
~~~

`socket:bind` binds a socket to a port. The socket should be
provided as the socket id, and the port number should be a
string. This will return 0 if successful, -1 if not successful,
and a host specific error code.

~~~
:socket:bind          (:sn-n)   #2 socket:operation ;
~~~

`socket:listen` prepares a socket for accepting incoming
connections. Takes a backlog count and a socket id. Returns
a flag (0 success, -1 failed) and an error code.

~~~
:socket:listen        (:nn-nn)  #3 socket:operation ;
~~~

`socket:accept` begins accepting connections on the provided
socket id. Returns a new socket id and an error code.

~~~
:socket:accept        (:n-nn)   #4 socket:operation ;
~~~

`socket:connect` connects to a server. Provide a socket id,
this will return a status flag and an error code.

~~~
:socket:connect       (:n-nn)   #5 socket:operation ;
~~~

`socket:send` sends a string to a socket. This will return
the number of characters sent and an error code. It takes a
string and a socket id.

~~~
:socket:send          (:sn-nn)  #6 socket:operation ;
~~~

`socket:recv` is a wrapper over recv(2). It takes an address,
a maxmimum number of bytes to read, and a socket id. It returns
the number of bytes received and an error code.

~~~
:socket:recv          (:ann-nn) #7 socket:operation ;
~~~

`socket:close` is a wrapper over close(2). It takes a socket id
and closes the socket.

~~~
:socket:close         (:n-)     #8 socket:operation ;
~~~

`socket:configure` is used before `socket:bind` to set some
internal state. Takes the host name and port, both as strings.
Does not return anything.

~~~
:socket:configure     (:ss-)    #9 socket:operation ;
~~~

# Source Data

~~~
'interface/sockets.retro
dup 'socket:configure     d:set-source
dup 'socket:close         d:set-source
dup 'socket:recv          d:set-source
dup 'socket:send          d:set-source
dup 'socket:connect       d:set-source
dup 'socket:accept        d:set-source
dup 'socket:listen        d:set-source
dup 'socket:bind          d:set-source
dup 'socket:create        d:set-source
dup 'socket:gethostbyname d:set-source
dup 'socket:operation     d:set-source
drop
~~~