Download
Docs

Contact
About
Docs
CVS

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.

 

 

Flux, these web pages, and all related material are Copyright©1999-2000 Simplemente and the respective authors, and are licensed under the GNU GPL. Please see the About page for more details. Web design by Joakim Ziegler <joakim@simplemente.net>, illustrations by Belinda Laws, <boysdontcry@zombieworld.com>.