tor

The Tor anonymity network
git clone https://git.dasho.dev/tor.git
Log | Files | Refs | README | LICENSE

tor_api.h (4864B)

      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-2021, 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 
     33 typedef struct tor_main_configuration_t tor_main_configuration_t;
     34 
     35 /**
     36 * Create and return a new tor_main_configuration().
     37 */
     38 tor_main_configuration_t *tor_main_configuration_new(void);
     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 */
     49 int tor_main_configuration_set_command_line(tor_main_configuration_t *cfg,
     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 */
     61 tor_control_socket_t tor_main_configuration_setup_control_socket(
     62                                          tor_main_configuration_t *cfg);
     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 */
     70 void tor_main_configuration_free(tor_main_configuration_t *cfg);
     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 */
    115 int tor_run_main(const tor_main_configuration_t *);
    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) */