[src/trunk]: src/share/man/man7 Add some more text from FreeBSD.

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/c5a636425323
branches:  trunk
changeset: 823396:c5a636425323
user:      christos <christos%NetBSD.org@localhost>
date:      Fri Apr 21 20:17:26 2017 +0000

description:
Add some more text from FreeBSD.

diffstat:

 share/man/man7/symlink.7 |  88 ++++++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 81 insertions(+), 7 deletions(-)

diffs (171 lines):

diff -r 6124fe1cf0f8 -r c5a636425323 share/man/man7/symlink.7
--- a/share/man/man7/symlink.7  Fri Apr 21 19:38:35 2017 +0000
+++ b/share/man/man7/symlink.7  Fri Apr 21 20:17:26 2017 +0000
@@ -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 @@
 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 @@
 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 @@
 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 @@
 .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 @@
 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 @@
 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 ,
+and
 .Nm chgrp
-and
-.Nm file
 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 @@
 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