tor_runner.c File Reference

Experimental module to emulate tor_run_main() API with fork+exec. More...

#include "feature/api/tor_api.h"
#include "feature/api/tor_api_internal.h"
#include "orconfig.h"
#include <stdlib.h>
#include <string.h>

Go to the source code of this file.

Macros
#define	__attribute__(x)
#define	real_calloc   calloc
#define	real_free   free

Functions
static void	child (const tor_main_configuration_t *cfg)
const char *	tor_api_get_provider_version (void)
int	tor_run_main (const tor_main_configuration_t *cfg)

Detailed Description

Experimental module to emulate tor_run_main() API with fork+exec.

The functions here are meant to allow the application developer to use the tor_run_main() API without having to care whether Tor is running in-process or out-of-process. For in-process usage, the developer can link Tor as a library and call tor_run_main(); for out-of-process usage, the developer can link this library instead.

This interface is EXPERIMENTAL; please let us know if you would like to depend on it. We don't know yet whether it will be reliable in practice.

Definition in file tor_runner.c.

Function Documentation

tor_api_get_provider_version()

const char* tor_api_get_provider_version

(

void

)

Return the name and version of the software implementing the tor_api functionality. Current implementors are "tor" and "libtorrunner".

Note that if you're using libtorrunner, you'll see the version of libtorrunner, not the version of Tor that it's invoking for you.

Added in Tor 0.3.5.1-alpha.

Example return values include "tor 0.3.5.1-alpha" when linked directly against tor, and "libtorrunner 0.3.5.1-alpha" when linked against libtorrunner while it is invoking an arbitrary version of Tor. HOWEVER, the user MUST NOT depend on any particular format or contents of this string: there may be other things that implement Tor in the future.

Definition at line 50 of file tor_runner.c.

tor_run_main()

int tor_run_main

(

const tor_main_configuration_t *

tor_cfg

)

Run the tor process, as if from the command line.

The command line arguments from tor_main_configuration_set_command_line() are taken as if they had been passed to main().

This function will not return until Tor is done running. It returns zero on success, and nonzero on failure.

If you want to control when Tor exits, make sure to configure a control socket. The OwningControllerFD option may be helpful there.

BUG 23847: Sometimes, if you call tor_main a second time (after it has returned), Tor may crash or behave strangely. We have fixed all issues of this type that we could find, but more may remain.

LIMITATION: You cannot run more than one instance of Tor in the same process at the same time. Concurrent calls will cause undefined behavior. We do not currently have plans to change this.

LIMITATION: While we will try to fix any problems found here, you should be aware that Tor was originally written to run as its own process, and that the functionality of this file was added later. If you find any bugs or strange behavior, please report them, and we'll try to straighten them out.

Definition at line 56 of file tor_runner.c.