1 files changed, 84 insertions, 1 deletions
diff --git a/manual/filesys.texi b/manual/filesys.texi
index e54f63dfc5..d7ab4e4a7f 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -1065,7 +1065,23 @@ purpose is to obtain information about the link.  @code{link}, the
 function that makes a hard link, does too.  It makes a hard link to the
 symbolic link, which one rarely wants.
 
-Prototypes for the functions listed in this section are in
+Some systems have for some functions operating on files have a limit on
+how many symbolic links are followed when resolving a path name.  The
+limit if it exists is published in the @file{sys/param.h} header file.
+
+@comment sys/param.h
+@comment BSD
+@deftypevr Macro int MAXSYMLINKS
+
+The macro @code{MAXSYMLINKS} specifies how many symlinks some function
+will follow before returning @code{ELOOP}.  Not all functions behave the
+same and this value is not the same a that returned for
+@code{_SC_SYMLOOP} by @code{sysconf}.  In fact, the @code{sysconf}
+result can indicate that there is no fixed limit although
+@code{MAXSYMLINKS} exists and has a finite value.
+@end deftypevr
+
+Prototypes for most of the functions listed in this section are in
 @file{unistd.h}.
 @pindex unistd.h
 
@@ -1153,6 +1169,73 @@ A hardware error occurred while reading or writing data on the disk.
 @c @end group
 @end deftypefun
 
+In some situations it is desirable to resolve all the to get the real
+name of a file where no prefix names a symbolic link which is followed
+and no filename in the path is @code{.} or @code{..}.  This is for
+instance desirable if files have to be compare in which case different
+names can refer to the same inode.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun {char *} canonicalize_file_name (const char *@var{name})
+
+The @code{canonicalize_file_name} function returns the absolute name of
+the file named by @var{name} which contains no @code{.}, @code{..}
+components nor any repeated path separators (@code{/}) or symlinks.  The
+result is passed back as the return value of the function in a block of
+memory allocated with @code{malloc}.  If the result is not used anymore
+the memory should be freed with a call to @code{free}.
+
+In any of the path components except the last one is missing the
+function returns a NULL pointer.  This is also what is returned if the
+length of the path reaches or exceeds @code{PATH_MAX} characters.  In
+any case @code{errno} is set accordingly.
+
+@table @code
+@item ENAMETOOLONG
+The resulting path is too long.  This error only occurs on systems which
+have a limit on the file name length.
+
+@item EACCES
+At least one of the path components is not readable.
+
+@item ENOENT
+The input file name is empty.
+
+@item ENOENT
+At least one of the path components does not exist.
+
+@item ELOOP
+More than @code{MAXSYMLINKS} many symlinks have been followed.
+@end table
+
+This function is a GNU extension and is declared in @file{stdlib.h}.
+@end deftypefun
+
+The Unix standard includes a similar function which differs from
+@code{canonicalize_file_name} in that the user has to provide the buffer
+where the result is placed in.
+
+@comment stdlib.h
+@comment XPG
+@deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved})
+
+The @code{realpath} function behaves just like
+@code{canonicalize_file_name} but instead of allocating a buffer for the
+result it is placed in the buffer pointed to by @var{resolved}.
+
+One other difference is that the buffer @var{resolved} will contain the
+part of the path component which does not exist or is not readable if
+the function returns @code{NULL} and @code{errno} is set to
+@code{EACCES} or @code{ENOENT}.
+
+This function is declared in @file{stdlib.h}.
+@end deftypefun
+
+The advantage of using this function is that it is more widely
+available.  The drawback is that it reports failures for long path on
+systems which have no limits on the file name length.
+
 @node Deleting Files
 @section Deleting Files
 @cindex deleting a file