Module Name: src
Committed By: christos
Date: Fri Apr 21 20:17:26 UTC 2017
Modified Files:
src/share/man/man7: symlink.7
Log Message:
Add some more text from FreeBSD.
To generate a diff of this commit:
cvs rdiff -u -r1.23 -r1.24 src/share/man/man7/symlink.7
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man7/symlink.7
diff -u src/share/man/man7/symlink.7:1.23 src/share/man/man7/symlink.7:1.24
--- src/share/man/man7/symlink.7:1.23 Fri Jan 10 04:44:30 2014
+++ src/share/man/man7/symlink.7 Fri Apr 21 16:17:26 2017
@@ -1,4 +1,4 @@
-.\" $NetBSD: symlink.7,v 1.23 2014/01/10 09:44:30 wiz Exp $
+.\" $NetBSD: symlink.7,v 1.24 2017/04/21 20:17:26 christos Exp $
.\"
.\" Copyright (c) 1992, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
@@ -29,7 +29,7 @@
.\"
.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94
.\"
-.Dd January 9, 2014
+.Dd April 21, 2017
.Dt SYMLINK 7
.Os
.Sh NAME
@@ -107,16 +107,20 @@ the system call
would return a file descriptor to the file
.Qq afile .
.Pp
-There are eight system calls that do not follow links, and which operate
+There are twelve system calls that do not follow links, and which operate
on the symbolic link itself.
They are:
.Xr lchflags 2 ,
.Xr lchmod 2 ,
.Xr lchown 2 ,
+.\".Xr lpathconf 2 ,
.Xr lstat 2 ,
.Xr lutimes 2 ,
.Xr readlink 2 ,
+.Xr readlinkat 2 ,
.Xr rename 2 ,
+.Xr renameat 2 ,
+.Xr unlinkat 2 .
and
.Xr unlink 2 .
Because
@@ -124,6 +128,48 @@ Because
is an alias for
.Xr unlink 2 ,
it also does not follow symbolic links.
+When
+.Xr rmdir 2
+or
+.Xr unlinkat 2
+with the
+.Dv AT_REMOVEDIR
+flag
+is applied to a symbolic link, it fails with the error
+.Er ENOTDIR .
+.Pp
+The
+.Xr linkat 2
+system call does not follow symbolic links
+unless given the
+.Dv AT_SYMLINK_FOLLOW
+flag.
+.Pp
+The following system calls follow symbolic links
+unless given the
+.Dv AT_SYMLINK_NOFOLLOW
+flag:
+.\" .Xr chflagsat 2 ,
+.Xr fchmodat 2 ,
+.Xr fchownat 2 ,
+.Xr fstatat 2
+and
+.Xr utimensat 2 .
+.Pp
+The owner and group of an existing symbolic link can be changed by
+means of the
+.Xr lchown 2
+system call.
+The flags, access permissions, owner/group and modification time of
+an existing symbolic link can be changed by means of the
+.Xr lchflags 2 ,
+.Xr lchmod 2 ,
+.Xr lchown 2 ,
+and
+.Xr lutimes 2
+system calls, respectively.
+Of these, only the flags and ownership are used by the system;
+the access permissions are ignored.
.Pp
The
.Bx 4.4
@@ -132,6 +178,11 @@ system differs from historical
systems in that the system call
.Xr chown 2
has been changed to follow symbolic links.
+The
+.Xr lchown 2
+system call was added later when the limitations of the new
+.Xr chown 2
+became apparent.
.Pp
If the filesystem is mounted with the
.Em symperm
@@ -193,7 +244,7 @@ would report that
.Qq Li slink
was a symbolic link.
.Pp
-There are three exceptions to this rule.
+There are five exceptions to this rule.
The
.Xr mv 1
and
@@ -216,6 +267,8 @@ option is not specified),
the
.Nm ls
command follows symbolic links named as arguments if the
+.\" .Fl H
+.\" or
.Fl L
option is specified,
or if the
@@ -231,19 +284,31 @@ option is specified,
always follows symbolic links.
.Nm ls
is the only command where the
+.\" .Fl H
+.\" and
.Fl L
option affects its behavior even though it is not doing a walk of
a file tree).
.Pp
The
+.Xr file 1
+and
+.Xr stat 1
+commands are also exceptions to this rule.
+These
+commands do not follow symbolic links named as argument by default,
+but do follow symbolic links named as argument if the
+.Fl L
+option is specified.
+.Pp
+The
.Bx 4.4
system differs from historical
.Bx 4
systems in that the
.Nm chown ,
-.Nm chgrp
and
-.Nm file
+.Nm chgrp
commands follow symbolic links specified on the command line.
.Ss Commands traversing a file tree
The following commands either optionally or always traverse file trees:
@@ -414,7 +479,16 @@ options.
To maintain compatibility with historic systems,
the
.Nm ls
-command never follows symbolic links unless the
+command acts a little differently.
+If you do not specify the
+.Fl F ,
+.Fl d
+or
+.Fl l
+options,
+.Nm ls
+will follow symbolic links specified on the command line.
+If the
.Fl L
flag is specified.
If the
