getcwd.3: Add details on the getcwd() syscall and how it used by libc functions

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/getcwd.3 b/man3/getcwd.3
index cb5b11bbcc5d3d71de04f610083f9fc200f46ecd..0f048d353ed770f23d56455ee3e395995ee89ab8 100644 (file)
--- a/man3/getcwd.3
+++ b/man3/getcwd.3
@@ -266,6 +266,25 @@ to return is usually a faster and more reliable alternative when sufficiently
 many file descriptors are available, especially on platforms other than Linux.
 .\"
 .SS C library/kernel differences
+On Linux, the kernel provides a
+.BR getcwd ()
+system call, which the functions described in this page will use if possible.
+The system call takes the same arguments as the library function
+of the same name, but is limited to returning at most
+.BR PATH_MAX
+bytes.
+(Before Linux 3.12,
+.\" commit 3272c544da48f8915a0e34189182aed029bd0f2b
+the limit on the size of the returned pathname was the system page size.
+On many architectures,
+.BR PATH_MAX
+and the system page size are both 4096 bytes,
+but a few architectures have a larger page size.)
+If the length of the pathname of the current working directory
+exceeds this limit, then the system call fails with the error
+.BR ENAMETOOLONG .
+In this case, the library functions fall back to
+a (slower) alternative implementation that returns the full pathname.
 .PP
 Following a change in Linux 2.6.36,
 .\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74