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

# tmain(3)

Tom main loop functions

## NAME

tmain - Tom main loop functions

## SYNOPSIS

\#include \<roy.h\>

void tmain (void);

void tmain\_quit (void);

int tmain\_timeout\_add (unsigned int ms, char \*description, \
                        TMainTimeoutEventFunction function, \
                        void \*user\_data);

int tmain\_idle\_add (char \*description, \
                     TMainIdleEventFunction function, \
                     void \*user\_data);

int tmain\_fd\_add (int fd, char \*description, \
                   TMainEventType event\_types, \
                   TMainFDEventFunction function, \
                   void \*user\_data);

int tmain\_socket\_add (SOCKET fd, char \*description, \
                       TMainEventType event\_types, \
                       TMainSocketEventFunction function, \
                       void \*user\_data);

void tmain\_remove (int id);

char \* tmain\_description (int id);

## DESCRIPTION

tmain implements a fairly standard, event driven mainloop. Entries of various types are added via the add functions above. [*tmain*(3)](/tmain/3.md) is then called, and when events occur as defined by the added entries, the applicable callback function is called, alerting the programmer to the event.

A call to *tmain\_timeout\_add*(3) will add a timeout event to the mainloop.  *ms* is the number of milliseconds before the callback function is called.  *description* is the description of this entry, as used for debugging purposes. *function* is a pointer to the callback function, and *user\_data* is a pointer to any data you wish to have available in the  callback function.  The timeout callback function (of course the name can be of your choosing) should be declared as:

```
    void tmain_timeout_callback (int id, void *user_data);
```

A call to *tmain\_idle\_add*(3) creates a new entry that will be called whenever something else is not being done in the mainloop.  In the event of multiple idle events, each will be called in sequence one after the other.  Arguments are identical to *tmain\_timeout\_add*(3).  The timeout\_add callback should be defined as:

```
    void tmain_idle_callback (int id, void *user_data);
```

*tmain\_fd\_add*(3) adds a file descriptor to the mainloop for watching.  *fd* is the file descriptor to watch, and *event\_types* should contain one or both of the flags *TMAIN\_READ* and/or *TMAIN\_WRITE*, depending on if you wish to watch for the readiness of the file descriptor for reading, or writing, or both.  The callback function for tmain\_fd\_add should be defined as:

```
    void tmain_fd_callback (int id, int fd,
                            TMainEventType event_type,
                            void *user_data);
```

Where *event\_type* will contain the flags which caused this callback to be called.  Again, one of *TMAIN\_READ* or *TMAIN\_WRITE*

*tmain\_socket\_add*(3) is identical to *tmain\_fd\_add*(3), but is used for sockets descriptors.  This is done for compatability with winsock sockets which have a different socket type. The callback function for *tmain\_socket\_add*(3) is identical to that for *tmain\_fd\_add*(3).

*tmain\_description*(3) returns the description of the entry as passed in during creation.  *id* is the id returned from the creation function.

*tmain\_remove*(3) removes an entry from the mainloop, and frees any associated memory.  It will not close file descriptors or sockets.

*tmain\_quit*(3) exits the mainloop and allows program flow to continue passed the call to [*tmain*(3)](/tmain/3.md).

[*tmain*(3)](/tmain/3.md) starts the mainloop.  After calling this function it will remain in control until *tmain\_quit*(3) is called.

## RETURN VALUES

All the add functions return an integer id that represents that entry in the mainloop.  *tmain\_description()* returns a string containing the description of the entry *id*.

## ERRORS

None of these functions produce any errors.  If an error occurs on a socket, the callback will be called with whatever status was being checked for, and will then fail in the read, write, recv, or send call, which should check for errors.

## DEBUGGING

The tmain loop uses the [*rdebug*(3)](/rdebug/3.md) facility to log debugging notices.  Adding 'tmain' to the *rdebug\_enable*(3) *domains* argument will print verbose status information about each entry, identified by its description.

## SEE ALSO

[*tom*(3)](/tom/3.md), [*roy*(3)](/roy/3.md), [*rdebug*(3)](/rdebug/3.md)