tor_api.h 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  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-2017, The Tor Project, Inc. */
  5. /* See LICENSE for licensing information */
  6. /**
  7. * \file tor_api.h
  8. * \brief Public C API for the Tor network service.
  9. *
  10. * This interface is intended for use by programs that need to link Tor as
  11. * a library, and launch it in a separate thread. If you have the ability
  12. * to run Tor as a separate executable, you should probably do that instead
  13. * of embedding it as a library.
  14. *
  15. * To use this API, first construct a tor_main_configuration_t object using
  16. * tor_main_configuration_new(). Then, you use one or more other function
  17. * calls (such as tor_main_configuration_set_command_line() to configure how
  18. * Tor should be run. Finally, you pass the configuration object to
  19. * tor_run_main().
  20. *
  21. * At this point, tor_run_main() will block its thread to run a Tor daemon;
  22. * when the Tor daemon exits, it will return. See notes on bugs and
  23. * limitations below.
  24. *
  25. * There is no other public C API to Tor: calling any C Tor function not
  26. * documented in this file is not guaranteed to be stable.
  27. **/
  28. #ifndef TOR_API_H
  29. #define TOR_API_H
  30. typedef struct tor_main_configuration_t tor_main_configuration_t;
  31. /**
  32. * Create and return a new tor_main_configuration().
  33. */
  34. tor_main_configuration_t *tor_main_configuration_new(void);
  35. /**
  36. * Set the command-line arguments in <b>cfg</b>.
  37. *
  38. * The <b>argc</b> and <b>argv</b> values here are as for main(). The
  39. * contents of the argv pointer must remain unchanged until tor_run_main() has
  40. * finished and you call tor_main_configuration_free().
  41. *
  42. * Return 0 on success, -1 on failure.
  43. */
  44. int tor_main_configuration_set_command_line(tor_main_configuration_t *cfg,
  45. int argc, char *argv[]);
  46. /**
  47. * Release all storage held in <b>cfg</b>.
  48. *
  49. * Once you have passed a tor_main_configuration_t to tor_run_main(), you
  50. * must not free it until tor_run_main() has finished.
  51. */
  52. void tor_main_configuration_free(tor_main_configuration_t *cfg);
  53. /**
  54. * Run the tor process, as if from the command line.
  55. *
  56. * The command line arguments from tor_main_configuration_set_command_line()
  57. * are taken as if they had been passed to main().
  58. *
  59. * This function will not return until Tor is done running. It returns zero
  60. * on success, and nonzero on failure.
  61. *
  62. * If you want to control when Tor exits, make sure to configure a control
  63. * socket. The OwningControllerFD option may be helpful there.
  64. *
  65. * BUG 23847: Sometimes, if you call tor_main a second time (after it has
  66. * returned), Tor may crash or behave strangely. We have fixed all issues of
  67. * this type that we could find, but more may remain.
  68. *
  69. * LIMITATION: You cannot run more than one instance of Tor in the same
  70. * process at the same time. Concurrent calls will cause undefined behavior.
  71. * We do not currently have plans to change this.
  72. *
  73. * LIMITATION: While we will try to fix any problems found here, you
  74. * should be aware that Tor was originally written to run as its own
  75. * process, and that the functionality of this file was added later. If
  76. * you find any bugs or strange behavior, please report them, and we'll
  77. * try to straighten them out.
  78. */
  79. int tor_run_main(const tor_main_configuration_t *);
  80. /**
  81. * Run the tor process, as if from the command line.
  82. *
  83. * @deprecated Using this function from outside Tor is deprecated; you should
  84. * use tor_run_main() instead.
  85. *
  86. * BUGS: This function has all the same bugs as tor_run_main().
  87. *
  88. * LIMITATIONS: This function has all the limitations of tor_run_main().
  89. */
  90. int tor_main(int argc, char **argv);
  91. #endif /* !defined(TOR_API_H) */