osn

Files in the top-level directory from the latest check-in

---

socket errors:
nil, error message[, errno]
special error messages:
nil, "closed" socket is closed (may apply only to receive OR send)
nil, "timeout" receiving/sending did run into a timeout
               -> on receive there might be:
                  "", "timeout" (just retry)
                  nil, "timeout" (better give up)
nil, "signal", sig, message, signo
               -> sig is one of: {"int", "term", "pipe", "usr1", "usr2"}

== connect / serve (/ udp_socket) ==
connect to a server / start a server
arg1: table:
 => port or usock must be set
 - usock: string unix socket path
 - port: string port (or service)
 - ip: string ip (or name)
 => all other are optional
 - family: string - default, depends on IP/usock
 - protocol: string - "[t]cp" (default), "[u]dp"
 - tcp_nodelay: boolean (advanced setting, default false)
 => connect supports:
 - connect_timeout: integer timeout in milliseconds
 => serve supports:
 - remove_socket_before_start: boolean (default false)
 - socket_mode: string mode
 => udp_socket supports: No optional field - protocol is udp
optional connect arg2:
 => udp usock
 - usock: string unix socket path
 - remove_socket_before_start: boolean (default false)
 - socket_mode: string mode
return:
arg1: socket - (un)connected or bound (and listen)
return on error: nil, message[, errno]

== close ==
return:
arg1: true
return on error: nil, message[, errno]
-> socket.closed will be true

=== listen socket ===
exist only for tcp -> serve

== accept ==
return:
optional arg1: socket (connected)
optional arg2: timeout in us
return on error: nil, message[, errno]
return on timeout: socket (closed), "timeout"

The first arg to accept can be a socket for reuse.
(a bit of performance win, no discard (gc), create cycle)
The secound arg can be a timeout in us.
If the timeout occurs, the return will be the (closed) socket and "timeout" as second arg.
In that case don't use the socket, but accept can be called again, with the socket to be recycled.
In an error case, the first return value will be nil -> don't call accept again.

=== connected socket ===

== getpeername ==
return:
arg1: string ip / unix socket path
arg2: port
return on error: nil, message[, errno]

== receive ==
arg1: integer size
optional arg2: long polling - "BLOCK" (forever) or n seconds (0 < n)
return:
arg1: string read
arg2 (udp): -> sender address (required for send)
return on error: nil, message[, errno]

== send ==
arg1: string data
arg2 (unconnected udp): -> address (returned by receive) or address table
return:
arg1: integer size
return on error: nil, message[, errno]