NAME

catgen_listen - install listener sessions

SYNOPSIS

#include <cat/gen.h>

int catgen_listen(catgen_sessfunc *func, void *data);

DESCRIPTION

This function starts listening to all sockets as specified on the command line by -P arguments. The arguments must have been parsed by catgen_parseargs() or catgen_getopt().

The func argument is an event callback that will be invoked when a new connection is received. func can be supplied as NULL.

A catgen_sessfunc is defined as follows:

typedef int catgen_sessfunc(cat_session *sess, const char *port, void *data);

The sess parameter is the current session, the port parameter is the local port number specified as a string, and data is the data passed to catgen_listen. The function should return CAT_CONTINUE if the SDK is to continue to forward data between the server and client.

Depending on platform, configuration, and compilation environment, func() can be called in a separate process or in a separate thread of the same process. It can also be called within the same thread as other sessions. It is therefore important that the func function does not block.

Before the callback is called, catgen_listen() will have established the following prerequisites for the session:

If no user-supplied callback has been defined, data is propagated between the client and server until either side closes the connection or the session times out.

RETURN VALUES

The function returns 0 if successful, or a negative error code on error.

LOGGING

If the Agent fails to connect to the server, provided that a server has been defined, the CATGEN_CONNFAIL event is logged.

NOTES

If this function returns an error, the best action is probably to exit the Agent. There is no graceful recovery.

The catgen_server function calls catgen_listen.

SEE ALSO

cat, catgen

catgen_getopt, catgen_parseargs, catgen_run, catgen_server, catgen_newport