LDP: Update original to LDP v3.68

[linuxjm/LDP_man-pages.git] / original / man7 / symlink.7

diff --git a/original/man7/symlink.7 b/original/man7/symlink.7
index 236b88b..50c9c17 100644 (file)
--- a/original/man7/symlink.7
+++ b/original/man7/symlink.7
@@ -1,5 +1,6 @@
 .\" Copyright (c) 1992, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
+.\" and Copyright (C) 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(BSD_3_CLAUSE_UCB)
 .\" Redistribution and use in source and binary forms, with or without
@@ -33,10 +34,10 @@
 .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for
 .\"     specific Linux details, improved readability, and man-pages style.
 .\"
-.TH SYMLINK 7 2008-06-18 "Linux" "Linux Programmer's Manual"
+.TH SYMLINK 7 2014-04-06 "Linux" "Linux Programmer's Manual"
 .SH NAME
 symlink \- symbolic link handling
-.SH SYMBOLIC LINK HANDLING
+.SH DESCRIPTION
 Symbolic links are files that act as pointers to other files.
 To understand their behavior, you must first understand how hard links
 work.
@@ -58,7 +59,9 @@ and may not refer to files on different filesystems
 (because i-node numbers are not unique across filesystems).
 
 A symbolic link is a special type of file whose contents are a string
-that is the pathname another file, the file to which the link refers.
+that is the pathname of another file, the file to which the link refers.
+(The contents of a symbolic link can be read using
+.BR readlink (2).)
 In other words, a symbolic link is a pointer to another name,
 and not to an underlying object.
 For this reason, symbolic links may refer to directories and may cross
@@ -114,6 +117,40 @@ and can't be changed.
 .\" system call was added later when the limitations of the new
 .\" .BR chown (2)
 .\" became apparent.
+.SS Obtaining a file descriptor that refers to a symbolic link
+Using the combination of the
+.B O_PATH
+and
+.BR O_NOFOLLOW
+flags to
+.BR open (2)
+yields a file descriptor that can be passed as the
+.IR dirfd
+argument in system calls such as
+.BR fstatat (2),
+.BR fchownat (2),
+.BR fchmodat (2),
+.BR linkat (2),
+and
+.BR readlinkat (2),
+in order to operate on the symbolic link itself
+(rather than the file to which it refers).
+
+By default
+(i.e., if the
+.BR AT_SYMLINK_FOLLOW
+flag is not specified), if
+.BR name_to_handle_at (2)
+is applied to a symbolic link, it yields a handle for the symbolic link
+(rather than the file to which it refers).
+One can then obtain a file descriptor for the symbolic link
+(rather than the file to which it refers)
+by specifying the
+.B O_PATH
+flag in a subsequent call to
+.BR open_by_handle_at (2).
+Again, that file descriptor can be used in the
+aforementioned system calls to operate on the symbolic link itself.
 .SS Handling of symbolic links by system calls and commands
 Symbolic links are handled either by operating on the link itself,
 or by operating on the object referred to by the link.
@@ -169,6 +206,7 @@ They are:
 .BR rmdir (2),
 and
 .BR unlink (2).
+
 Certain other system calls optionally follow symbolic links.
 They are:
 .BR faccessat (2),
@@ -176,8 +214,10 @@ They are:
 .BR fchownat (2),
 .BR fstatat (2),
 .BR linkat (2),
+.BR name_to_handle_at (2),
 .BR open (2),
 .BR openat (2),
+.BR open_by_handle_at (2),
 and
 .BR utimensat (2);
 see their manual pages for details.
@@ -190,6 +230,7 @@ When
 .BR rmdir (2)
 is applied to a symbolic link, it fails with the error
 .BR ENOTDIR .
+
 The
 .BR link (2)
 warrants special discussion.
@@ -220,7 +261,7 @@ would display the contents of the file
 .IR afile .
 
 It is important to realize that this rule includes commands which may
-optionally traverse file trees, e.g., the command
+optionally traverse file trees; for example, the command
 .I "chown file"
 is included in this rule, while the command
 .IR "chown\ \-R file" ,
@@ -228,11 +269,11 @@ which performs a tree traversal, is not.
 (The latter is described in the third area, below.)
 
 If it is explicitly intended that the command operate on the symbolic
-link instead of following the symbolic link, e.g., it is desired that
+link instead of following the symbolic link\(emfor example, it is desired that
 .I "chown slink"
 change the ownership of the file that
 .I slink
-is, whether it is a symbolic link or not, the
+is, whether it is a symbolic link or not\(emthe
 .I \-h
 option should be used.
 In the above example,
@@ -262,7 +303,7 @@ The
 command is also an exception to this rule.
 For compatibility with historic systems (when
 .BR ls (1)
-is not doing a tree walk, i.e., the
+is not doing a tree walk\(emthat is,
 .I \-R
 option is not specified),
 the
@@ -486,3 +527,12 @@ whether specified on the command line or encountered in the tree walk.
 .BR utimensat (2),
 .BR lutimes (3),
 .BR path_resolution (7)
+.SH COLOPHON
+This page is part of release 3.68 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.