|
Tor 0.4.9.0-alpha-dev
|
Public C API for the Tor network service. More...
Go to the source code of this file.
Macros | |
| #define | INVALID_TOR_CONTROL_SOCKET (-1) |
Typedefs | |
| typedef int | tor_control_socket_t |
Functions | |
| tor_main_configuration_t * | tor_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) |
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.
| 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.
| int tor_main | ( | int | argc, |
| char ** | argv | ||
| ) |
Run the tor process, as if from the command line.
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().
| 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.
| tor_main_configuration_t * tor_main_configuration_new | ( | void | ) |
| 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.
| tor_control_socket_t tor_main_configuration_setup_control_socket | ( | tor_main_configuration_t * | cfg | ) |
| 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.
1.9.4