tom(3)

NAME

tom - the tom library

SYNOPSIS

#include <roy.h>

int tmisc_winsock_check_init (void);

char * socketstrerror (void);

DESCRIPTION

The Tom library implements a thin, portable socket layer, and featureful mainloop implementation that works on both unix and win32 systems.

The socket layer is very thin, and provides only a few functions and macros to make sockets compatible on unix and win32 (winsock). Unfortunately it requires that you do a few things differently from the standard unix sockets API, but the changes are slight.

The mainloop implements timeouts, file descriptor and socket watching, and idle function calls. See the tmain(3) manpage for details on Tom mainloop usage.

To link the Tom library into your application, use roy-config(1) with the tom module argument.

SOCKETS

Tom implements a minimal number of functions, constants and types to allow sockets to be used on both unix and winsock based systems without changes to the users code. Usage of sockets is identical to standard BSD socket(3) API, with the following exceptions:

Windows Initalization

Before any socket code is used, the function tmisc_winsock_check_init() should be called. This function returns -1 on error, and 0 on success. This initializes the winsock library on win32, but is ignored on unix systems, so no #ifdef is required around it.

For example:

    if (tmisc_winsock_check_init () < 0) {
        fprintf (stderr, "No winsock dll found, or old version.\n");
        fprintf (stderr, "Unable to initialize socket interface.\n");
        exit (1);
    }

SOCKET type

Instead of using an integer for a socket file descriptor, the SOCKET type is used. To declare a socket f, you would use:

SOCKET f;

Socket Creation Testing

After calling socket(2), the returned socket should be checked by comparing it to the constant INVALID_SOCKET. This is defined appropriately on each platform to be the value of a bad socket.

For example:

    SOCKET f;

    f = socket (AF_INET, SOCK_STREAM, 0);
    if (f == INVALID_SOCKET) {
        fprintf (stderr, 
                 "Unable to create socket: %s\n", 
                 socketstrerror ());
        exit (1);
    }

Socket Error Messages

Instead of using strerror(3) to return the error on a socket, the function socketstrerror(3) is used. Usage is identical, but also works with winsock.

Using send/recv

On windows, file descriptors are not used in the same way for sockets, so the read(2) and write(2) system calls will not work for these sockets. Because of this, you should always use recv(2) and send(2) instead.

SEE ALSO

roy(3), tmain(3), roy-config(1)