commit f221a7aaf6f05670f0d19f66c792d3b96f385f43 Author: Nick Mathewson <nickm@torproject.org> Date: Tue Nov 12 12:28:14 2019 -0500 Fold remainder of this-not-that.md into CodingStandards.md --- doc/HACKING/CodingStandards.md | 30 +++++++++++++++++----- doc/HACKING/design/this-not-that.md | 51 ------------------------------------- 2 files changed, 24 insertions(+), 57 deletions(-) diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 966a2b810..34d1dd52b 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -212,7 +212,8 @@ deviations from our C whitespace style. Generally, we use: - No space between a function name and an opening paren. `puts(x)`, not `puts (x)`. - Function declarations at the start of the line. - - Use `void foo(void)` to declare a function with no arguments. + - Use `void foo(void)` to declare a function with no arguments. Saying + `void foo()` is C++ syntax. - Use `const` for new APIs. If you use an editor that has plugins for editorconfig.org, the file @@ -230,22 +231,32 @@ We have some wrapper functions like `tor_malloc`, `tor_free`, `tor_strdup`, and `tor_gettimeofday;` use them instead of their generic equivalents. (They always succeed or exit.) +Specifically, Don't use `malloc`, `realloc`, `calloc`, `free`, or +`strdup`. Use `tor_malloc`, `tor_realloc`, `tor_calloc`, `tor_free`, or +`tor_strdup`. + +Don't use `tor_realloc(x, y\*z)`. Use `tor_reallocarray(x, y, z)` instead.; + You can get a full list of the compatibility functions that Tor provides by looking through `src/lib/*/*.h`. You can see the available containers in `src/lib/containers/*.h`. You should probably familiarize yourself with these modules before you write too much code, or else you'll wind up reinventing the wheel. -We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously broken -old C functions. Use `strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead. + +We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously +broken old C functions. We also avoid `strncat` and `strncpy`. Use +`strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead. We don't call `memcmp()` directly. Use `fast_memeq()`, `fast_memneq()`, -`tor_memeq()`, or `tor_memneq()` for most purposes. +`tor_memeq()`, or `tor_memneq()` for most purposes. If you really need a +tristate return value, use `tor_memcmp()` or `fast_memcmp()`. Don't call `assert()` directly. For hard asserts, use `tor_assert()`. For soft asserts, use `tor_assert_nonfatal()` or `BUG()`. If you need to print debug information in assert error message, consider using `tor_assertf()` and -`tor_assertf_nonfatal()`. +`tor_assertf_nonfatal()`. If you are writing code that is too low-level to +use the logging subsystem, use `raw_assert()`. Don't use `toupper()` and `tolower()` functions. Use `TOR_TOUPPER` and `TOR_TOLOWER` macros instead. Similarly, use `TOR_ISALPHA`, `TOR_ISALNUM` et. @@ -258,6 +269,12 @@ Avoid calling BSD socket functions directly. Use portable wrappers to work with sockets and socket addresses. Also, sockets should be of type `tor_socket_t`. +Don't use any of these functions: they aren't portable. Use the +version prefixed with `tor_` instead: strtok_r, memmem, memstr, +asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton, +getpass, ntohll, htonll. (This list is incomplete.) + + What code can use what other code? ---------------------------------- @@ -350,7 +367,8 @@ Binary data and wire formats ---------------------------- Use pointer to `char` when representing NUL-terminated string. To represent -arbitrary binary data, use pointer to `uint8_t`. +arbitrary binary data, use pointer to `uint8_t`. (Many older Tor APIs ignore +this rule.) Refrain from attempting to encode integers by casting their pointers to byte arrays. Use something like `set_uint32()`/`get_uint32()` instead and don't diff --git a/doc/HACKING/design/this-not-that.md b/doc/HACKING/design/this-not-that.md deleted file mode 100644 index 815c7b2fb..000000000 --- a/doc/HACKING/design/this-not-that.md +++ /dev/null @@ -1,51 +0,0 @@ - -Don't use memcmp. Use {tor,fast}_{memeq,memneq,memcmp}. - -Don't use assert. Use tor_assert or tor_assert_nonfatal or BUG. Prefer -nonfatal assertions or BUG()s. - -Don't use sprintf or snprintf. Use tor_asprintf or tor_snprintf. - -Don't write hand-written binary parsers. Use trunnel. - -Don't use malloc, realloc, calloc, free, strdup, etc. Use tor_malloc, -tor_realloc, tor_calloc, tor_free, tor_strdup, etc. - -Don't use tor_realloc(x, y\*z). Use tor_reallocarray(x, y, z); - -Don't say "if (x) foo_free(x)". Just foo_free(x) and make sure that -foo_free(NULL) is a no-op. - -Don't use toupper or tolower; use TOR_TOUPPER and TOR_TOLOWER. - -Don't use isalpha, isalnum, etc. Instead use TOR_ISALPHA, TOR_ISALNUM, etc. - -Don't use strcat, strcpy, strncat, or strncpy. Use strlcat and strlcpy -instead. - -Don't use tor_asprintf then smartlist_add; use smartlist_add_asprintf. - -Don't use any of these functions: they aren't portable. Use the -version prefixed with `tor_` instead: strtok_r, memmem, memstr, -asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton, -getpass, ntohll, htonll, strdup, (This list is incomplete.) - -Don't create or close sockets directly. Instead use the wrappers in -compat.h. - -When creating new APIs, only use 'char \*' to represent 'pointer to a -nul-terminated string'. Represent 'pointer to a chunk of memory' as -'uint8_t \*'. (Many older Tor APIs ignore this rule.) - -Don't encode/decode u32, u64, or u16 to byte arrays by casting -pointers. That can crash if the pointers aren't aligned, and can cause -endianness problems. Instead say something more like set_uint32(ptr, -htonl(foo)) to encode, and ntohl(get_uint32(ptr)) to decode. - -Don't declare a 0-argument function with "void foo()". That's C++ -syntax. In C you say "void foo(void)". - -When creating new APIs, use const everywhere you reasonably can. - -Sockets should have type tor_socket_t, not int. -