tor  0.4.2.0-alpha-dev
Macros | Typedefs | Functions
tor_api.h File Reference

Go to the source code of this file.

Macros

#define INVALID_TOR_CONTROL_SOCKET   (-1)
 

Typedefs

typedef struct tor_main_configuration_t tor_main_configuration_t
 
typedef int tor_control_socket_t
 

Functions

tor_main_configuration_ttor_main_configuration_new (void)
 
int tor_main_configuration_set_command_line (tor_main_configuration_t *cfg, int argc, char *argv[])
 
tor_control_socket_t tor_main_configuration_setup_control_socket (tor_main_configuration_t *cfg)
 
void tor_main_configuration_free (tor_main_configuration_t *cfg)
 
const char * tor_api_get_provider_version (void)
 
int tor_run_main (const tor_main_configuration_t *)
 
int tor_main (int argc, char **argv)
 

Detailed Description

Public C API for the Tor network service.

This interface is intended for use by programs that need to link Tor as a library, and launch it in a separate thread. If you have the ability to run Tor as a separate executable, you should probably do that instead of embedding it as a library.

To use this API, first construct a tor_main_configuration_t object using tor_main_configuration_new(). Then, you use one or more other function calls (such as tor_main_configuration_set_command_line() to configure how Tor should be run. Finally, you pass the configuration object to tor_run_main().

At this point, tor_run_main() will block its thread to run a Tor daemon; when the Tor daemon exits, it will return. See notes on bugs and limitations below.

There is no other public C API to Tor: calling any C Tor function not documented in this file is not guaranteed to be stable.

Definition in file tor_api.h.

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 139 of file tor_api.c.

◆ tor_main()

int tor_main ( int  argc,
char **  argv 
)

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

Deprecated:
Using this function from outside Tor is deprecated; you should use tor_run_main() instead.

BUGS: This function has all the same bugs as tor_run_main().

LIMITATIONS: This function has all the limitations of tor_run_main().

Referenced by main().

◆ tor_main_configuration_free()

void tor_main_configuration_free ( tor_main_configuration_t cfg)

Release all storage held in cfg.

Once you have passed a tor_main_configuration_t to tor_run_main(), you must not free it until tor_run_main() has finished.

Definition at line 122 of file tor_api.c.

References tor_main_configuration_t::argc_owned, and tor_main_configuration_t::argv_owned.

◆ tor_main_configuration_new()

tor_main_configuration_t* tor_main_configuration_new ( void  )

Create and return a new tor_main_configuration().

Definition at line 73 of file tor_api.c.

◆ tor_main_configuration_set_command_line()

int tor_main_configuration_set_command_line ( tor_main_configuration_t cfg,
int  argc,
char *  argv[] 
)

Set the command-line arguments in cfg.

The argc and argv values here are as for main(). The contents of the argv pointer must remain unchanged until tor_run_main() has finished and you call tor_main_configuration_free().

Return 0 on success, -1 on failure.

Definition at line 91 of file tor_api.c.

References tor_main_configuration_t::argc, and tor_main_configuration_t::argv.

◆ tor_main_configuration_setup_control_socket()

tor_control_socket_t tor_main_configuration_setup_control_socket ( tor_main_configuration_t cfg)

DOCDOC

Definition at line 102 of file tor_api.c.

References tor_main_configuration_t::owning_controller_socket, and SOCKET_OK.

◆ tor_run_main()

int tor_run_main ( const tor_main_configuration_t )

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 1263 of file main.c.

References tor_main_configuration_t::argc, tor_main_configuration_t::argc_owned, init_protocol_warning_severity_level(), tor_free_(), tor_malloc_(), and tor_realloc_().