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.
|