Tor  0.4.3.0-alpha-dev
tor_api.h
Go to the documentation of this file.
1 /* Copyright (c) 2001 Matej Pfajfar.
2  * Copyright (c) 2001-2004, Roger Dingledine.
3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4  * Copyright (c) 2007-2020, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * \file tor_api.h
9  * \brief Public C API for the Tor network service.
10  *
11  * This interface is intended for use by programs that need to link Tor as
12  * a library, and launch it in a separate thread. If you have the ability
13  * to run Tor as a separate executable, you should probably do that instead
14  * of embedding it as a library.
15  *
16  * To use this API, first construct a tor_main_configuration_t object using
17  * tor_main_configuration_new(). Then, you use one or more other function
18  * calls (such as tor_main_configuration_set_command_line() to configure how
19  * Tor should be run. Finally, you pass the configuration object to
20  * tor_run_main().
21  *
22  * At this point, tor_run_main() will block its thread to run a Tor daemon;
23  * when the Tor daemon exits, it will return. See notes on bugs and
24  * limitations below.
25  *
26  * There is no other public C API to Tor: calling any C Tor function not
27  * documented in this file is not guaranteed to be stable.
28  **/
29 
30 #ifndef TOR_API_H
31 #define TOR_API_H
32 
34 
35 /**
36  * Create and return a new tor_main_configuration().
37  */
39 
40 /**
41  * Set the command-line arguments in <b>cfg</b>.
42  *
43  * The <b>argc</b> and <b>argv</b> values here are as for main(). The
44  * contents of the argv pointer must remain unchanged until tor_run_main() has
45  * finished and you call tor_main_configuration_free().
46  *
47  * Return 0 on success, -1 on failure.
48  */
50  int argc, char *argv[]);
51 
52 #ifdef _WIN32
53 typedef SOCKET tor_control_socket_t;
54 #define INVALID_TOR_CONTROL_SOCKET INVALID_SOCKET
55 #else
56 typedef int tor_control_socket_t;
57 #define INVALID_TOR_CONTROL_SOCKET (-1)
58 #endif /* defined(_WIN32) */
59 
60 /** DOCDOC */
63 
64 /**
65  * Release all storage held in <b>cfg</b>.
66  *
67  * Once you have passed a tor_main_configuration_t to tor_run_main(), you
68  * must not free it until tor_run_main() has finished.
69  */
71 
72 /**
73  * Return the name and version of the software implementing the tor_api
74  * functionality. Current implementors are "tor" and "libtorrunner".
75  *
76  * Note that if you're using libtorrunner, you'll see the version of
77  * libtorrunner, not the version of Tor that it's invoking for you.
78  *
79  * Added in Tor 0.3.5.1-alpha.
80  *
81  * Example return values include "tor 0.3.5.1-alpha" when linked directly
82  * against tor, and "libtorrunner 0.3.5.1-alpha" when linked against
83  * libtorrunner while it is invoking an arbitrary version of Tor. HOWEVER,
84  * the user MUST NOT depend on any particular format or contents of this
85  * string: there may be other things that implement Tor in the future.
86  **/
87 const char *tor_api_get_provider_version(void);
88 
89 /**
90  * Run the tor process, as if from the command line.
91  *
92  * The command line arguments from tor_main_configuration_set_command_line()
93  * are taken as if they had been passed to main().
94  *
95  * This function will not return until Tor is done running. It returns zero
96  * on success, and nonzero on failure.
97  *
98  * If you want to control when Tor exits, make sure to configure a control
99  * socket. The OwningControllerFD option may be helpful there.
100  *
101  * BUG 23847: Sometimes, if you call tor_main a second time (after it has
102  * returned), Tor may crash or behave strangely. We have fixed all issues of
103  * this type that we could find, but more may remain.
104  *
105  * LIMITATION: You cannot run more than one instance of Tor in the same
106  * process at the same time. Concurrent calls will cause undefined behavior.
107  * We do not currently have plans to change this.
108  *
109  * LIMITATION: While we will try to fix any problems found here, you
110  * should be aware that Tor was originally written to run as its own
111  * process, and that the functionality of this file was added later. If
112  * you find any bugs or strange behavior, please report them, and we'll
113  * try to straighten them out.
114  */
116 
117 /**
118  * Run the tor process, as if from the command line.
119  *
120  * @deprecated Using this function from outside Tor is deprecated; you should
121  * use tor_run_main() instead.
122  *
123  * BUGS: This function has all the same bugs as tor_run_main().
124  *
125  * LIMITATIONS: This function has all the limitations of tor_run_main().
126  */
127 int tor_main(int argc, char **argv);
128 
129 #endif /* !defined(TOR_API_H) */
void tor_main_configuration_free(tor_main_configuration_t *cfg)
Definition: tor_api.c:122
int tor_main_configuration_set_command_line(tor_main_configuration_t *cfg, int argc, char *argv[])
Definition: tor_api.c:91
int tor_main(int argc, char **argv)
int tor_run_main(const tor_main_configuration_t *)
Definition: main.c:1222
tor_control_socket_t tor_main_configuration_setup_control_socket(tor_main_configuration_t *cfg)
Definition: tor_api.c:102
const char * tor_api_get_provider_version(void)
Definition: tor_api.c:139
tor_main_configuration_t * tor_main_configuration_new(void)
Definition: tor_api.c:73