From 4e5db0ad4a5720b74670e3519dd1f2fea41980a1 Mon Sep 17 00:00:00 2001
From: Martin Pool <mbp@samba.org>
Date: Mon, 8 Apr 2002 05:21:51 +0000
Subject: [PATCH] Doc.

---
 flist.c |  9 ++++++++-
 util.c  | 17 ++++++++++++++---
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/flist.c b/flist.c
index cbae6442..381eb8e4 100644
--- a/flist.c
+++ b/flist.c
@@ -196,8 +196,15 @@ static void list_file_entry(struct file_struct *f)
  * Stat either a symlink or its referent, depending on the settings of
  * copy_links, copy_unsafe_links, etc.
  *
- * @return -1 on error; or 0.  If a symlink, then @p Linkbuf (of size
+ * @retval -1 on error
+ *
+ * @retval 0 for success
+ *
+ * @post If @p path is a symlink, then @p linkbuf (of size @c
  * MAXPATHLEN) contains the symlink target.
+ *
+ * @post @p buffer contains information about the link or the
+ * referrent as appropriate, if they exist.
  **/
 int readlink_stat(const char *path, STRUCT_STAT * buffer, char *linkbuf)
 {
diff --git a/util.c b/util.c
index 0f5a410a..21ace4df 100644
--- a/util.c
+++ b/util.c
@@ -700,8 +700,10 @@ void sanitize_path(char *p, char *reldir)
 
 static char curr_dir[MAXPATHLEN];
 
-/** like chdir() but can be reversed with pop_dir() if save is set. It
-   is also much faster as it remembers where we have been */
+/**
+ * Like chdir() but can be reversed with pop_dir() if @p save is set.
+ * It is also much faster as it remembers where we have been.
+ **/
 char *push_dir(char *dir, int save)
 {
 	char *ret = curr_dir;
@@ -732,7 +734,7 @@ char *push_dir(char *dir, int save)
 	return ret;
 }
 
-/** Reverse a push_dir call */
+/** Reverse a push_dir() call */
 int pop_dir(char *dir)
 {
 	int ret;
@@ -772,6 +774,13 @@ int u_strcmp(const char *cs1, const char *cs2)
  * else's machine it might allow them to establish a symlink to
  * /etc/passwd, and then read it through a web server.
  *
+ * Null symlinks and absolute symlinks are always unsafe.
+ *
+ * Basically here we are concerned with symlinks whose target contains
+ * "..", because this might cause us to walk back up out of the
+ * transferred directory.  We are not allowed to go back up and
+ * reenter.
+ *
  * @param dest Target of the symlink in question.
  *
  * @param src Top source directory currently applicable.  Basically this
@@ -780,6 +789,8 @@ int u_strcmp(const char *cs1, const char *cs2)
  *
  * @retval True if unsafe
  * @retval False is unsafe
+ *
+ * @sa t_unsafe.c
  **/
 int unsafe_symlink(char *dest, char *src)
 {
-- 
2.34.1