[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [tor/master] Improved documentation and comments #25140



commit 0b633b1f6d022a359806a705bd4a6082d92bd3f3
Author: Daniel Pinto <danielpinto52@xxxxxxxxx>
Date:   Tue Aug 11 18:26:41 2020 +0100

    Improved documentation and comments #25140
---
 doc/man/tor.1.txt |   6 ++--
 src/lib/fs/path.c | 104 ++++++++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 88 insertions(+), 22 deletions(-)

diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt
index bb01315d46..3febf43513 100644
--- a/doc/man/tor.1.txt
+++ b/doc/man/tor.1.txt
@@ -206,9 +206,9 @@ such multiline entries, but they must start at the beginning of a line.
 
 Configuration options can be imported from files or folders using the %include
 option with the value being a path. This path can have wildcards. Wildcards are 
-expanded first, using lexical order. Then, for each matching file or folder, the 
-following rules are followed: if the path is a file, the options from the 
-file will be parsed as if they were written where the %include option is. If
+expanded first, then sorted using lexical order. Then, for each matching file or 
+folder, the following rules are followed: if the path is a file, the options from 
+the file will be parsed as if they were written where the %include option is. If
 the path is a folder, all files on that folder will be parsed following lexical
 order. Files starting with a dot are ignored. Files in subfolders are ignored.
 The %include option can be used recursively.
diff --git a/src/lib/fs/path.c b/src/lib/fs/path.c
index 4532bfb7d1..1a60ca70d4 100644
--- a/src/lib/fs/path.c
+++ b/src/lib/fs/path.c
@@ -44,13 +44,6 @@
 #include <errno.h>
 #include <string.h>
 
-#ifdef _WIN32
-#define IS_GLOB_CHAR(s,i) (((s)[(i)]) == '*' || ((s)[(i)]) == '?')
-#else
-#define IS_GLOB_CHAR(s,i) ((((s)[(i)]) == '*' || ((s)[(i)]) == '?') &&\
-                           ((i) == 0 || (s)[(i)-1] != '\\')) /* check escape */
-#endif
-
 /** Removes enclosing quotes from <b>path</b> and unescapes quotes between the
  * enclosing quotes. Backslashes are not unescaped. Return the unquoted
  * <b>path</b> on success or 0 if <b>path</b> is not quoted correctly. */
@@ -321,8 +314,78 @@ make_path_absolute(const char *fname)
 #endif /* defined(_WIN32) */
 }
 
-/** Expands globs in <b>pattern</b> for the path fragment between
- * <b>prev_sep</b> and <b>next_sep</b>. Returns NULL on failure. */
+/* The code below implements tor_glob and get_glob_opened_files. Because it is
+ * not easy to understand it by looking at individual functions, the big
+ * picture explanation here should be read first.
+ *
+ * Purpose of the functions:
+ * - tor_glob - recevies a pattern and returns all the paths that result from
+ *   its glob expansion, globs can be present on all path components.
+ * - get_glob_opened_files - receives a pattern and returns all the paths that
+ *   are opened during its expansion (the paths before any path fragment that
+ *   contains a glob as they have to be opened to check for glob matches). This
+ *   is used to get the paths that have to be added to the seccomp sandbox
+ *   allowed list.
+ *
+ * Due to OS API differences explained below, the implementation of tor_glob is
+ * completly different for Windows and POSIX systems, so we ended up with three
+ * different implementations:
+ * - tor_glob for POSIX - as POSIX glob does everything we need, we simply call
+ *   it and process the results. This is completly implemented in tor_glob.
+ * - tor_glob for WIN32 - because the WIN32 API only supports expanding globs
+ *   in the last path fragment, we need to expand the globs in each path
+ *   fragment manually and call recursively to get the same behaviour as POSIX
+ *   glob. When there are no globs in pattern, we know we are on the last path
+ *   fragment and collect the full path.
+ * - get_glob_opened_files - because the paths before any path fragment with a
+ *   glob will be opened to check for matches, we need to collect them and we
+ *   need to expand the globs in each path fragments and call recursively until
+ *   we find no more globs.
+ *
+ * As seen from the description above, both tor_glob for WIN32 and
+ * get_glob_opened_files receive a pattern and return a list of paths and have
+ * to expand all path fragments that contain globs and call themselves
+ * recursively. The differences are:
+ * - get_glob_opened_files collects paths before path fragments with globs
+ *   while tor_glob for WIN32 collects full paths resulting from the expansion
+ *   of all globs.
+ * - get_glob_opened_files can call tor_glob to expand path fragments with
+ *   globs while tor_glob for WIN32 cannot because it IS tor_glob. For tor_glob
+ *   for WIN32, an auxiliary function has to be used for this purpose.
+ *
+ * To avoid code duplication, the logic of tor_glob for WIN32 and
+ * get_glob_opened_files is implemented in get_glob_paths. The differences are
+ * configured by the extra function parameters:
+ * - final - if true, returns a list of paths obtained from expanding pattern
+ *   (implements tor_glob). Otherwise, returns the paths before path fragments
+ *   with globs (implements get_glob_opened_files).
+ * - unglob - function used to expand a path fragment. The function signature
+ *   is defined by the unglob_fn typedef. Two implementations are available:
+ *   - unglob_win32 - uses tor_listdir and PathMatchSpec (for tor_glob WIN32)
+ *   - unglob_opened_files - uses tor_glob (for get_glob_opened_files)
+ */
+
+/** Returns true if the character at position <b>pos</b> in <b>pattern</b> is
+ * considered a glob. Returns false otherwise. Takes escaping into account on
+ * systems where escaping globs is supported. */
+static inline bool
+is_glob_char(const char *pattern, int pos)
+{
+  bool is_glob = pattern[pos] == '*' || pattern[pos] == '?';
+#ifdef _WIN32
+  return is_glob;
+#else /* !defined(_WIN32) */
+  bool is_escaped = pos > 0 && pattern[pos-1] == '\\';
+  return is_glob && !is_escaped;
+#endif /* defined(_WIN32) */
+}
+
+/** Expands the first path fragment of <b>pattern</b> that contains globs. The
+ * path fragment is between <b>prev_sep</b> and <b>next_sep</b>. If the path
+ * fragment is the last fragment of <b>pattern</b>, <b>next_sep</b> will be the
+ * index of the last char. Returns a list of paths resulting from the glob
+ * expansion of the path fragment. Anything after <b>next_sep</b> is not
+ * included in the returned list. Returns NULL on failure. */
 typedef struct smartlist_t * unglob_fn(const char *pattern, int prev_sep,
                                        int next_sep);
 
@@ -350,7 +413,7 @@ add_non_glob_path(const char *path, struct smartlist_t *result)
  * expand each path fragment. If <b>final</b> is true, the paths are the result
  * of the glob expansion of <b>pattern</b> (implements tor_glob). Otherwise,
  * the paths are the paths opened by glob while expanding <b>pattern</b>
- * (implements get_glb_opened_files). Returns NULL on failure. */
+ * (implements get_glob_opened_files). Returns NULL on failure. */
 static struct smartlist_t *
 get_glob_paths(const char *pattern, unglob_fn unglob, bool final)
 {
@@ -360,7 +423,7 @@ get_glob_paths(const char *pattern, unglob_fn unglob, bool final)
 
   // find first path fragment with globs
   for (i = 0; pattern[i]; i++) {
-    is_glob = is_glob || IS_GLOB_CHAR(pattern, i);
+    is_glob = is_glob || is_glob_char(pattern, i);
     is_last = !pattern[i+1];
     is_sep = pattern[i] == *PATH_SEPARATOR || pattern[i] == '/';
     if (is_sep || is_last) {
@@ -422,7 +485,8 @@ end:
 #ifdef _WIN32
 /** Expands globs in <b>pattern</b> for the path fragment between
  * <b>prev_sep</b> and <b>next_sep</b> using the WIN32 API. Returns NULL on
- * failure. Used by the WIN32 implementation of tor_glob. */
+ * failure. Used by the WIN32 implementation of tor_glob. Implements unglob_fn,
+ * see its description for more details. */
 static struct smartlist_t *
 unglob_win32(const char *pattern, int prev_sep, int next_sep)
 {
@@ -450,10 +514,10 @@ unglob_win32(const char *pattern, int prev_sep, int next_sep)
 #ifdef UNICODE
         mbstowcs(tpattern, path_curr_glob, MAX_PATH);
         mbstowcs(tfile, full_path, MAX_PATH);
-#else
+#else /* !defined(UNICODE) */
         strlcpy(tpattern, path_curr_glob, MAX_PATH);
         strlcpy(tfile, full_path, MAX_PATH);
-#endif
+#endif /* defined(UNICODE) */
         if (PathMatchSpec(tfile, tpattern)) {
           smartlist_add(result, full_path);
         } else {
@@ -492,7 +556,8 @@ prot_lstat(const char *pathname, struct stat *buf)
 #endif /* defined(_WIN32) */
 
 /** Return a new list containing the paths that match the pattern
- * <b>pattern</b>. Return NULL on error.
+ * <b>pattern</b>. Return NULL on error. On POSIX systems, errno is set by the
+ * glob function.
  */
 struct smartlist_t *
 tor_glob(const char *pattern)
@@ -548,7 +613,7 @@ has_glob(const char *s)
 {
   int i;
   for (i = 0; s[i]; i++) {
-    if (IS_GLOB_CHAR(s, i)) {
+    if (is_glob_char(s, i)) {
       return true;
     }
   }
@@ -557,7 +622,8 @@ has_glob(const char *s)
 
 /** Expands globs in <b>pattern</b> for the path fragment between
  * <b>prev_sep</b> and <b>next_sep</b> using tor_glob. Returns NULL on
- * failure. Used by get_glob_opened_files. */
+ * failure. Used by get_glob_opened_files. Implements unglob_fn, see its
+ * description for more details. */
 static struct smartlist_t *
 unglob_opened_files(const char *pattern, int prev_sep, int next_sep)
 {
@@ -565,8 +631,8 @@ unglob_opened_files(const char *pattern, int prev_sep, int next_sep)
   smartlist_t *result = smartlist_new();
   // if the following fragments have no globs, we're done
   if (has_glob(&pattern[next_sep+1])) {
-    // if there is a glob after next_sep, we know it is a separator and not the
-    // last char and glob_path will have the path without the separator
+    // if there is a glob after next_sep, we know next_sep is a separator and
+    // not the last char and glob_path will have the path without the separator
     char *glob_path = tor_strndup(pattern, next_sep);
     smartlist_t *child_paths = tor_glob(glob_path);
     tor_free(glob_path);



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits