---
name: "tom"
section: "3"
platform: "linux"
package: "libroy-dev"
version: "1.0.2-1"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/tom"
---

# tom(3)

the tom library

## 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)](/tmain/3.md) manpage for details on Tom mainloop usage.

To link the Tom library into your application, use [*roy-config*(1)](/roy-config/1.md) 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)](/socket/2.md), 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)](/strerror/3.md) 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)](/read/2.md) and [*write*(2)](/write/2.md) system calls will not work for these sockets.  Because of this, you should always use [*recv*(2)](/recv/2.md) and [*send*(2)](/send/2.md) instead.

## SEE ALSO

[*roy*(3)](/roy/3.md), [*tmain*(3)](/tmain/3.md), [*roy-config*(1)](/roy-config/1.md)