aboutsummaryrefslogtreecommitdiff
path: root/manual/filesys.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/filesys.texi')
-rw-r--r--manual/filesys.texi85
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