Reference: Sockets
General
The name of the socket layer is a little misleading, as it also covers
interprocess pipes. It is a generalized IPC/RPC stream API, with user-space
buffering which lets you avoid blocking (through look-ahead). Together with
the communications layer and proxies, this does a lot of the work (modelling
and typing) required to make a network client/server.
Properties overview
- Has two ends, one remote and one local to the process.
- Is streamed.
- Is buffered.
- Is bidirectional.
- Can connect two processes on the same machine and in the same process
group, through pipes.
- Can connect two processes on different machines, through TCP/IP.
- Offers simplified (stdio-like) stream reading/writing.
- When the result of an incoming connection, indicates which parent socket
spawned it.
Non-blocking operation
To do non-blocking reads/writes with a SOCK, you have to register it with a
PROXY and use buffering operations. The actual
transfer functions documented here are for simple programs that can afford
to block, or threaded implementations. It is up to the application
programmer to make sure he doesn't write more than the buffer can hold, or
read more than the buffer can provide, at a time. The functions sock_get_max_read and sock_get_max_write are intended for this.
Allocation
- SOCK *sock_new();
Creates a new, unconnected TCP/IP socket, with an automatically assigned port.
It does not accept incoming connections.
- SOCK *sock_pipe_new();
Creates a new loopback pipe. In its initial state, all data you send to it is
buffered and sent back to you.
- SOCK *sock_new_with_port(int port);
Creates a new, unconnected socket and binds it to a specific port (port). It does not accept incoming connections. This might
be useful if the other end expects connections to come from a specific
port on your host. Otherwise, you should just use sock_new.
- SOCK *sock_accepting_new(int port);
Creates a new, unconnected socket and binds it to port.
It will accept incoming connections.
- SOCK *sock_new_from_handles(int in, int
out);
Creates a new socket based on the Unix pipe handles given in in and out.
- SOCK *sock_new_from_files(FILE *in, FILE *out);
Creates a new socket based on the Unix stdio file handles given in in and out.
- void sock_del(SOCK *s);
Disconnects and frees any kind of SOCK, specified
by s.
Status information
- int sock_is_connecting(SOCK *s);
Returns TRUE if the socket is currently trying to
establish an outgoing connection (asynchronously).
- int sock_is_connected(SOCK *s);
Returns TRUE if the socket is connected at the
remote end.
- int sock_is_accepting(SOCK *s);
Returns TRUE if the socket will accept an
incoming connection attempt.
- int sock_is_active(SOCK *s);
Returns TRUE if the socket is either connected
or available for incoming connections.
- int sock_get_fd_read(SOCK *s);
Returns the file descriptor used to read from the socket, or -1 if it's
inactive.
- int sock_get_fd_write(SOCK *s);
Returns the file descriptor used to write to the socket, or -1 if it's
inactive.
- int sock_buf_in_size(SOCK *s);
Returns the size (in bytes) of incoming data currently in buffer.
- int sock_buf_out_size(SOCK *s);
Returns the size (in bytes) of outgoing data currently in buffer.
Connectivity
- int sock_pipe_parent(SOCK *s);
Splits an established loopback pipe and keeps the parent end. Used by the
parent process after a fork, to communicate with the child.
- int sock_pipe_child(SOCK *s);
Splits an established loopback pipe and keeps the child end. Used by the
child process after a fork, to communicate with the parent.
- int sock_connect(SOCK *s, char *desthost_str, int destport);
Tries to connect s to a remote host, with
address string in desthost_str, which can be
either a name or a dotted IP address, at the port specified by
destport. This function blocks execution until
the connection attempt is resolved.
- int sock_reconnect(SOCK *s);
Tries to connect s to the remote host it was last
connected to (and was disconnected from). This function blocks execution
until the connection attempt is resolved.
- int sock_disconnect(SOCK *s, unsigned long flags);
Disconnects from the remote host. The socket is left intact, and can be
recycled in subsequent connections. Use sock_del to
get rid of it entirely.
Stream monitoring
- SOCK *sock_wait(unsigned long timeout_usec, unsigned int options, SOCK *s,
...);
Waits for data (or a connection) to arrive on any of the sockets given, at most timeout_usec microseconds, or, if it's zero, indefinitely.
The list of sockets must end with a NULL.
Returns the socket that got data first, or, in the case of an incoming
connection, a newly created connected socket.
- SOCK *sock_wait_arr(unsigned long timeout_usec, unsigned int options, SOCK **s);
Waits for data (or a connection) to arrive on any of the sockets given in the array
s, at most timeout_usec microseconds, or, if it's zero, indefinitely.
The socket array must end with a NULL.
Returns the socket that got data first, or, in the case of an incoming
connection, a newly created connected socket.
- int sock_poll(SOCK *s);
Returns the number of incoming bytes pending on s,
after a non-blocking read.
Data; writing
- int sock_get_max_write(SOCK *s);
Returns the number of bytes you can write to s without
blocking.
- int sock_flush(SOCK *s);
Blocks until all data written to s is actually sent.
- int sock_write(SOCK *s, void *data, unsigned int size);
Writes size bytes of data to
s. May block.
- int sock_putc(SOCK *s, char c);
Writes the character c to s. May block.
- int sock_puts(SOCK *s, char *str);
Writes the string str to s. May block.
- int sock_printf(SOCK *s, char *format, ...);
Writes a formatted string to s, just like printf()
works on FILE streams.
Data; reading
- int sock_get_max_read(SOCK *s);
Returns the number of bytes you can read from s without
blocking. Equal to the incoming buffer size.
- int sock_read(SOCK *s, void *dest, unsigned int size);
Reads size bytes from s into
dest. May block.
- void *sock_dread(SOCK *s, unsigned int size);
Reads size bytes from s and
returns an allocated buffer containing the data. Returns NULL if the requested amount of data couldn't be read.
May block.
- int sock_gets(SOCK *s, char *dest, unsigned int size_max);
Reads at most size_max bytes from
s into dest, stopping if it
finds a linefeed (\n). The linefeed itself is not kept, and a zero is
appended at the end. May block.
- int sock_getc(SOCK *s);
Reads one byte from s and returns its value. Returns a
negative value if nothing could be read. May block.
- char *sock_dgets(SOCK *s);
Reads a line from from
s, stopping when it finds a linefeed (\n).
The linefeed itself is not kept, and a zero is appended at the end. The
string is returned in an allocated buffer. May block.
- int sock_scanf(SOCK *s, char *format, ...);
Reads a formatted string from s. The string must
represent a complete line - the rest is thrown away. May block.
Addresses
- const char *sock_get_remote_name(SOCK *s);
Returns a pointer to a statically allocated string representing the name of
the remote host (last) connected to s. Caches the name and
does not make unneccessary DNS lookups. Returns NULL if the host is not in DNS, or if the socket was
never connected.
- const char *sock_get_remote_ip(SOCK *s);
Returns a pointer to a statically allocated string representing the IP address
of the remote host (last) connected to s. Returns
NULL if the socket was never connected.
- const char *sock_get_remote_name_or_ip(SOCK *s);
Returns a pointer to a statically allocated string representing the name, or
failing that, IP address of the remote host (last) connected to s.
Returns NULL if the socket was never connected.
- void sock_set_timeout(SOCK *s, int timeout_sec);
Sets the generic timeout for operations on s, like
connecting and ping timeout.