getcwd.3: behavior for unreachable cwd

For the code that does this, see fs/dcache.c, search for "prepend_unreachable".

repro testcase:

$ cat getcwd.c
#define _GNU_SOURCE
#include <sched.h>
#include <unistd.h>
#include <stdio.h>
#include <limits.h>
#include <stdlib.h>

int main(void) {
unshare(CLONE_NEWUSER | CLONE_NEWNS);
chdir("/usr");
chroot("bin");

  printf("current directory: \"%s\"\n", get_current_dir_name());

  char *real = realpath(".", NULL);
  printf("realpath of .: \"%s\"\n", real ? real : "{none}");
  real = realpath("../home/jann/.ssh", NULL);
  printf("realpath of path: \"%s\"\n", real ? real : "{none}");

return 0;
}

$ cat getcwd_test.c
#define _GNU_SOURCE
#include <sched.h>
#include <unistd.h>
#include <stdio.h>

int main(void) {
unshare(CLONE_NEWUSER | CLONE_NEWNS);
chdir("/usr");
chroot("bin");
printf("current directory: \"%s\"\n", get_current_dir_name()); return 0;
}

$ gcc -o getcwd_test getcwd_test.c -Wall
$ ./getcwd_test
current directory: "(unreachable)/usr"

realpath.3 doesn't currently seem to handle this case in a sane way, so I'm not going to document its behavior yet. I'll report that as a bug instead.

---
 man3/getcwd.3 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

man3/getcwd.3 +13 -0

index a1f7e2a..6a98b82 100644
@@ -80,6 +80,19 @@ The pathname is returned as the function result and via the argument
 .IR buf ,
 if present.
 
+If the current directory is not below the root directory of the current
+process (e.g. because the process set a new filesystem root
+using
+.BR chroot (2)
+without changing its current directory into the new root), the returned
+path will be prefixed with the string "(unreachable)". Such behavior can
+also be caused by an unprivileged user by changing the current directory
+into another mount namespace.
+When dealing with paths from untrusted sources, callers of these
+functions should consider checking whether the returned path starts
+with '/' or '(' to avoid misinterpreting an unreachable path
+as a relative path.
+
 The
 .BR getcwd ()
 function copies an absolute pathname of the current working directory