2008-06-11 21:25:12 +00:00
|
|
|
.\" Copyright (c) 1992, 1993, 1994
|
|
|
|
.\" The Regents of the University of California. All rights reserved.
|
2014-03-18 04:19:35 +00:00
|
|
|
.\" and Copyright (C) 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
|
2008-06-11 21:25:12 +00:00
|
|
|
.\"
|
2013-03-10 16:43:17 +00:00
|
|
|
.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB)
|
2008-06-11 21:25:12 +00:00
|
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
|
|
.\" modification, are permitted provided that the following conditions
|
|
|
|
.\" are met:
|
|
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
|
|
.\" may be used to endorse or promote products derived from this software
|
|
|
|
.\" without specific prior written permission.
|
|
|
|
.\"
|
|
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
|
|
.\" SUCH DAMAGE.
|
accept.2, bind.2, connect.2, getpeername.2, getpriority.2, getsockname.2, getsockopt.2, ioctl.2, killpg.2, listen.2, lseek.2, readlink.2, recv.2, send.2, setpgid.2, setreuid.2, shutdown.2, socket.2, socketpair.2, syscall.2, truncate.2, alloca.3, btree.3, daemon.3, dbopen.3, err.3, exec.3, fclose.3, ferror.3, fflush.3, fopen.3, fread.3, fseek.3, fts.3, getloadavg.3, hash.3, mpool.3, openpty.3, popen.3, queue.3, rcmd.3, recno.3, rexec.3, scanf.3, setbuf.3, stdarg.3, stdio.3, strtod.3, hostname.7, mdoc.7, mdoc.samples.7, operator.7, symlink.7: Add LICENSE_START(BSD_[34]_CLAUSE_FULL)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-03-10 09:28:48 +00:00
|
|
|
.\" %%%LICENSE_END
|
2008-06-11 21:25:12 +00:00
|
|
|
.\"
|
|
|
|
.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94
|
|
|
|
.\" $FreeBSD: src/bin/ln/symlink.7,v 1.30 2005/02/13 22:25:09 ru Exp $
|
|
|
|
.\"
|
|
|
|
.\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for
|
|
|
|
.\" specific Linux details, improved readability, and man-pages style.
|
|
|
|
.\"
|
bdflush.2, fsync.2, mmap.2, open.2, perf_event_open.2, sync.2, syscall.2, fmemopen.3, getaddrinfo.3, getline.3, mq_notify.3, offsetof.3, aio.7, symlink.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2014-04-06 06:47:35 +00:00
|
|
|
.TH SYMLINK 7 2014-04-06 "Linux" "Linux Programmer's Manual"
|
2008-06-11 21:25:12 +00:00
|
|
|
.SH NAME
|
|
|
|
symlink \- symbolic link handling
|
2014-03-18 04:29:44 +00:00
|
|
|
.SH DESCRIPTION
|
2008-06-11 21:25:12 +00:00
|
|
|
Symbolic links are files that act as pointers to other files.
|
|
|
|
To understand their behavior, you must first understand how hard links
|
|
|
|
work.
|
2008-06-18 09:36:55 +00:00
|
|
|
|
2008-06-11 21:25:12 +00:00
|
|
|
A hard link to a file is indistinguishable from the original file because
|
|
|
|
it is a reference to the object underlying the original filename.
|
2008-06-18 09:36:55 +00:00
|
|
|
(To be precise: each of the hard links to a file is a reference to
|
|
|
|
the same
|
2014-11-12 21:32:40 +00:00
|
|
|
.IR "inode number" ,
|
|
|
|
where an inode number is an index into the inode table,
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
which contains metadata about all files on a filesystem.
|
2008-09-10 03:33:15 +00:00
|
|
|
See
|
2008-06-18 09:36:55 +00:00
|
|
|
.BR stat (2).)
|
2008-06-11 21:25:12 +00:00
|
|
|
Changes to a file are independent of the name used to reference the file.
|
|
|
|
Hard links may not refer to directories
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
(to prevent the possibility of loops within the filesystem tree,
|
2008-06-11 21:25:12 +00:00
|
|
|
which would confuse many programs)
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
and may not refer to files on different filesystems
|
2014-11-12 21:32:40 +00:00
|
|
|
(because inode numbers are not unique across filesystems).
|
2008-06-18 09:36:55 +00:00
|
|
|
|
2008-06-11 21:25:12 +00:00
|
|
|
A symbolic link is a special type of file whose contents are a string
|
2014-01-21 13:50:38 +00:00
|
|
|
that is the pathname of another file, the file to which the link refers.
|
2014-03-18 04:31:10 +00:00
|
|
|
(The contents of a symbolic link can be read using
|
|
|
|
.BR readlink (2).)
|
2008-06-11 21:25:12 +00:00
|
|
|
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
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
filesystem boundaries.
|
2008-06-11 21:25:12 +00:00
|
|
|
|
|
|
|
There is no requirement that the pathname referred to by a symbolic link
|
|
|
|
should exist.
|
|
|
|
A symbolic link that refers to a pathname that does not exist is said
|
2008-06-18 09:36:55 +00:00
|
|
|
to be a
|
|
|
|
.IR "dangling link" .
|
2008-06-11 21:25:12 +00:00
|
|
|
|
intro.1, time.1, access.2, acct.2, alloc_hugepages.2, bind.2, chdir.2, chmod.2, chown.2, chroot.2, clone.2, close.2, execve.2, fallocate.2, fcntl.2, getdents.2, getrusage.2, getxattr.2, init_module.2, inotify_add_watch.2, ioprio_set.2, kcmp.2, link.2, listxattr.2, lseek.2, madvise.2, mkdir.2, mknod.2, mmap.2, mount.2, move_pages.2, msgctl.2, nfsservctl.2, open.2, pivot_root.2, quotactl.2, read.2, readlink.2, removexattr.2, rename.2, rmdir.2, semctl.2, setfsgid.2, setfsuid.2, setresuid.2, setuid.2, setup.2, setxattr.2, shmctl.2, splice.2, spu_create.2, stat.2, statfs.2, swapon.2, symlink.2, sync.2, sync_file_range.2, sysfs.2, truncate.2, umount.2, unlink.2, unshare.2, ustat.2, utime.2, utimensat.2, write.2, btree.3, errno.3, fexecve.3, ftw.3, futimes.3, get_nprocs_conf.3, getcwd.3, getdirentries.3, getmntent.3, glob.3, mkfifo.3, mq_open.3, readdir.3, realpath.3, recno.3, remove.3, sem_open.3, shm_open.3, statvfs.3, sysconf.3, telldir.3, tmpfile.3, cciss.4, initrd.4, pts.4, sk98lin.4, vcs.4, core.5, filesystems.5, proc.5, boot.7, bootparam.7, capabilities.7, cpuset.7, credentials.7, feature_test_macros.7, fifo.7, hier.7, inotify.7, intro.7, mq_overview.7, path_resolution.7, pipe.7, sem_overview.7, shm_overview.7, spufs.7, symlink.7, unix.7, uri.7, sync.8: Global fix: s/file system/filesystem/
Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
"filesystem" is the form used by the great majority of man pages
outside the man-pages project and in a number of other sources,
so let's go with that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-08-08 08:07:57 +00:00
|
|
|
Because a symbolic link and its referenced object coexist in the filesystem
|
2008-06-11 21:25:12 +00:00
|
|
|
name space, confusion can arise in distinguishing between the link itself
|
|
|
|
and the referenced object.
|
|
|
|
On historical systems,
|
2008-06-18 09:36:55 +00:00
|
|
|
commands and system calls adopted their own link-following
|
|
|
|
conventions in a somewhat ad-hoc fashion.
|
2008-06-11 21:25:12 +00:00
|
|
|
Rules for a more uniform approach,
|
|
|
|
as they are implemented on Linux and other systems,
|
|
|
|
are outlined here.
|
|
|
|
It is important that site-local applications also conform to these rules,
|
|
|
|
so that the user interface can be as consistent as possible.
|
|
|
|
.SS Symbolic link ownership, permissions, and timestamps
|
|
|
|
The owner and group of an existing symbolic link can be changed
|
|
|
|
using
|
|
|
|
.BR lchown (2).
|
|
|
|
The only time that the ownership of a symbolic link matters is
|
|
|
|
when the link is being removed or renamed in a directory that
|
|
|
|
has the sticky bit set (see
|
|
|
|
.BR stat (2)).
|
|
|
|
|
|
|
|
The last access and last modification timestamps
|
|
|
|
of a symbolic link can be changed using
|
|
|
|
.BR utimensat (2)
|
|
|
|
or
|
|
|
|
.BR lutimes (3).
|
|
|
|
|
|
|
|
On Linux, the permissions of a symbolic link are not used
|
|
|
|
in any operations; the permissions are always
|
|
|
|
0777 (read, write, and execute for all user categories),
|
|
|
|
.\" Linux does not currently implement an lchmod(2).
|
|
|
|
and can't be changed.
|
|
|
|
.\"
|
|
|
|
.\" The
|
|
|
|
.\" 4.4BSD
|
|
|
|
.\" system differs from historical
|
|
|
|
.\" 4BSD
|
|
|
|
.\" systems in that the system call
|
|
|
|
.\" .BR chown (2)
|
|
|
|
.\" has been changed to follow symbolic links.
|
|
|
|
.\" The
|
|
|
|
.\" .BR lchown (2)
|
|
|
|
.\" system call was added later when the limitations of the new
|
|
|
|
.\" .BR chown (2)
|
|
|
|
.\" became apparent.
|
2014-03-17 13:36:08 +00:00
|
|
|
.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
|
2014-03-18 11:00:25 +00:00
|
|
|
flag in a subsequent call to
|
2014-03-17 13:36:08 +00:00
|
|
|
.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.
|
2008-06-11 21:25:12 +00:00
|
|
|
.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.
|
|
|
|
In the latter case,
|
2008-06-18 09:36:55 +00:00
|
|
|
an application or system call is said to
|
|
|
|
.I follow
|
|
|
|
the link.
|
2008-06-11 21:25:12 +00:00
|
|
|
Symbolic links may refer to other symbolic links,
|
|
|
|
in which case the links are dereferenced until an object that is
|
|
|
|
not a symbolic link is found,
|
|
|
|
a symbolic link that refers to a file which does not exist is found,
|
|
|
|
or a loop is detected.
|
|
|
|
(Loop detection is done by placing an upper limit on the number of
|
|
|
|
links that may be followed, and an error results if this limit is
|
|
|
|
exceeded.)
|
|
|
|
|
|
|
|
There are three separate areas that need to be discussed.
|
|
|
|
They are as follows:
|
|
|
|
.IP 1. 3
|
|
|
|
Symbolic links used as filename arguments for system calls.
|
|
|
|
.IP 2.
|
|
|
|
Symbolic links specified as command-line arguments to utilities that
|
|
|
|
are not traversing a file tree.
|
|
|
|
.IP 3.
|
|
|
|
Symbolic links encountered by utilities that are traversing a file tree
|
|
|
|
(either specified on the command line or encountered as part of the
|
|
|
|
file hierarchy walk).
|
|
|
|
.SS System calls
|
|
|
|
The first area is symbolic links used as filename arguments for
|
|
|
|
system calls.
|
|
|
|
|
|
|
|
Except as noted below, all system calls follow symbolic links.
|
|
|
|
For example, if there were a symbolic link
|
2008-06-18 09:36:55 +00:00
|
|
|
.I slink
|
2008-06-11 21:25:12 +00:00
|
|
|
which pointed to a file named
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR afile ,
|
2008-06-11 21:25:12 +00:00
|
|
|
the system call
|
2008-06-26 13:38:01 +00:00
|
|
|
.I "open(""slink"" ...\&)"
|
2008-06-11 21:25:12 +00:00
|
|
|
would return a file descriptor referring to the file
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR afile .
|
2008-06-11 21:25:12 +00:00
|
|
|
|
|
|
|
Various system calls do not follow links, and operate
|
|
|
|
on the symbolic link itself.
|
|
|
|
They are:
|
|
|
|
.BR lchown (2),
|
|
|
|
.BR lgetxattr (2),
|
|
|
|
.BR llistxattr (2),
|
|
|
|
.BR lremovexattr (2),
|
|
|
|
.BR lsetxattr (2),
|
|
|
|
.BR lstat (2),
|
|
|
|
.BR readlink (2),
|
|
|
|
.BR rename (2),
|
|
|
|
.BR rmdir (2),
|
|
|
|
and
|
|
|
|
.BR unlink (2).
|
2014-03-17 12:44:02 +00:00
|
|
|
|
2008-06-11 21:25:12 +00:00
|
|
|
Certain other system calls optionally follow symbolic links.
|
|
|
|
They are:
|
|
|
|
.BR faccessat (2),
|
|
|
|
.\" Maybe one day: .BR fchownat (2)
|
|
|
|
.BR fchownat (2),
|
|
|
|
.BR fstatat (2),
|
|
|
|
.BR linkat (2),
|
2014-03-17 12:40:00 +00:00
|
|
|
.BR name_to_handle_at (2),
|
2008-06-11 21:25:12 +00:00
|
|
|
.BR open (2),
|
|
|
|
.BR openat (2),
|
2014-03-17 12:40:00 +00:00
|
|
|
.BR open_by_handle_at (2),
|
2008-06-11 21:25:12 +00:00
|
|
|
and
|
|
|
|
.BR utimensat (2);
|
|
|
|
see their manual pages for details.
|
|
|
|
Because
|
|
|
|
.BR remove (3)
|
|
|
|
is an alias for
|
|
|
|
.BR unlink (2),
|
|
|
|
that library function also does not follow symbolic links.
|
|
|
|
When
|
|
|
|
.BR rmdir (2)
|
|
|
|
is applied to a symbolic link, it fails with the error
|
|
|
|
.BR ENOTDIR .
|
2014-03-17 12:44:02 +00:00
|
|
|
|
2008-06-11 21:25:12 +00:00
|
|
|
The
|
|
|
|
.BR link (2)
|
|
|
|
warrants special discussion.
|
|
|
|
POSIX.1-2001 specifies that
|
|
|
|
.BR link (2)
|
|
|
|
should dereference
|
|
|
|
.I oldpath
|
|
|
|
if it is a symbolic link.
|
|
|
|
However, Linux does not do this.
|
2015-03-27 11:22:41 +00:00
|
|
|
(By default, Solaris is the same,
|
2008-06-11 21:25:12 +00:00
|
|
|
but the POSIX.1-2001 specified behavior can be obtained with
|
|
|
|
suitable compiler options.)
|
|
|
|
The upcoming POSIX.1 revision changes the specification to allow
|
|
|
|
either behavior in an implementation.
|
|
|
|
.SS Commands not traversing a file tree
|
|
|
|
The second area is symbolic links, specified as command-line
|
|
|
|
filename arguments, to commands which are not traversing a file tree.
|
|
|
|
|
|
|
|
Except as noted below, commands follow symbolic links named as
|
|
|
|
command-line arguments.
|
|
|
|
For example, if there were a symbolic link
|
2008-06-18 09:36:55 +00:00
|
|
|
.I slink
|
2008-06-11 21:25:12 +00:00
|
|
|
which pointed to a file named
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR afile ,
|
2008-06-11 21:25:12 +00:00
|
|
|
the command
|
|
|
|
.I "cat slink"
|
|
|
|
would display the contents of the file
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR afile .
|
2008-06-11 21:25:12 +00:00
|
|
|
|
|
|
|
It is important to realize that this rule includes commands which may
|
2014-01-01 03:23:27 +00:00
|
|
|
optionally traverse file trees; for example, the command
|
2008-06-11 21:25:12 +00:00
|
|
|
.I "chown file"
|
|
|
|
is included in this rule, while the command
|
2008-06-26 13:19:40 +00:00
|
|
|
.IR "chown\ \-R file" ,
|
2008-06-11 21:25:12 +00:00
|
|
|
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
|
2014-01-01 03:23:27 +00:00
|
|
|
link instead of following the symbolic link\(emfor example, it is desired that
|
2008-06-11 21:25:12 +00:00
|
|
|
.I "chown slink"
|
|
|
|
change the ownership of the file that
|
2008-06-18 09:36:55 +00:00
|
|
|
.I slink
|
2014-01-01 03:23:27 +00:00
|
|
|
is, whether it is a symbolic link or not\(emthe
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-h
|
2008-06-11 21:25:12 +00:00
|
|
|
option should be used.
|
|
|
|
In the above example,
|
|
|
|
.I "chown root slink"
|
|
|
|
would change the ownership of the file referred to by
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR slink ,
|
2008-06-11 21:25:12 +00:00
|
|
|
while
|
2008-06-26 13:19:40 +00:00
|
|
|
.I "chown\ \-h root slink"
|
2008-06-11 21:25:12 +00:00
|
|
|
would change the ownership of
|
2008-06-18 09:36:55 +00:00
|
|
|
.I slink
|
2008-06-11 21:25:12 +00:00
|
|
|
itself.
|
|
|
|
|
|
|
|
There are some exceptions to this rule:
|
|
|
|
.IP * 2
|
|
|
|
The
|
|
|
|
.BR mv (1)
|
|
|
|
and
|
|
|
|
.BR rm (1)
|
|
|
|
commands do not follow symbolic links named as arguments,
|
|
|
|
but respectively attempt to rename and delete them.
|
|
|
|
(Note, if the symbolic link references a file via a relative path,
|
|
|
|
moving it to another directory may very well cause it to stop working,
|
|
|
|
since the path may no longer be correct.)
|
|
|
|
.IP *
|
|
|
|
The
|
|
|
|
.BR ls (1)
|
|
|
|
command is also an exception to this rule.
|
|
|
|
For compatibility with historic systems (when
|
|
|
|
.BR ls (1)
|
2014-01-01 03:15:14 +00:00
|
|
|
is not doing a tree walk\(emthat is,
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-R
|
2008-06-11 21:25:12 +00:00
|
|
|
option is not specified),
|
|
|
|
the
|
|
|
|
.BR ls (1)
|
|
|
|
command follows symbolic links named as arguments if the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-H
|
2008-06-11 21:25:12 +00:00
|
|
|
or
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-L
|
2008-06-11 21:25:12 +00:00
|
|
|
option is specified,
|
|
|
|
or if the
|
2008-06-26 12:56:53 +00:00
|
|
|
.IR \-F ,
|
|
|
|
.IR \-d ,
|
2008-06-11 21:25:12 +00:00
|
|
|
or
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-l
|
2008-06-11 21:25:12 +00:00
|
|
|
options are not specified.
|
|
|
|
(The
|
|
|
|
.BR ls (1)
|
|
|
|
command is the only command where the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-H
|
2008-06-11 21:25:12 +00:00
|
|
|
and
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-L
|
2008-06-11 21:25:12 +00:00
|
|
|
options affect its behavior even though it is not doing a walk of
|
|
|
|
a file tree.)
|
|
|
|
.IP *
|
|
|
|
The
|
|
|
|
.BR file (1)
|
|
|
|
command is also an exception to this rule.
|
|
|
|
The
|
|
|
|
.BR file (1)
|
|
|
|
command does not follow symbolic links named as argument by default.
|
|
|
|
The
|
|
|
|
.BR file (1)
|
|
|
|
command does follow symbolic links named as argument if the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-L
|
2008-06-11 21:25:12 +00:00
|
|
|
option is specified.
|
|
|
|
.\"
|
|
|
|
.\"The 4.4BSD system differs from historical 4BSD systems in that the
|
|
|
|
.\".BR chown (1)
|
|
|
|
.\"and
|
|
|
|
.\".BR chgrp (1)
|
|
|
|
.\"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:
|
|
|
|
.BR chgrp (1),
|
|
|
|
.BR chmod (1),
|
|
|
|
.BR chown (1),
|
|
|
|
.BR cp (1),
|
|
|
|
.BR du (1),
|
|
|
|
.BR find (1),
|
|
|
|
.BR ls (1),
|
|
|
|
.BR pax (1),
|
|
|
|
.BR rm (1),
|
|
|
|
and
|
|
|
|
.BR tar (1).
|
|
|
|
|
|
|
|
It is important to realize that the following rules apply equally to
|
|
|
|
symbolic links encountered during the file tree traversal and symbolic
|
|
|
|
links listed as command-line arguments.
|
|
|
|
|
|
|
|
The \fIfirst rule\fP applies to symbolic links that reference files other
|
|
|
|
than directories.
|
|
|
|
Operations that apply to symbolic links are performed on the links
|
|
|
|
themselves, but otherwise the links are ignored.
|
|
|
|
|
|
|
|
The command
|
2008-06-26 13:19:40 +00:00
|
|
|
.I "rm\ \-r slink directory"
|
2008-06-11 21:25:12 +00:00
|
|
|
will remove
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR slink ,
|
2008-06-11 21:25:12 +00:00
|
|
|
as well as any symbolic links encountered in the tree traversal of
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR directory ,
|
2008-06-11 21:25:12 +00:00
|
|
|
because symbolic links may be removed.
|
|
|
|
In no case will
|
|
|
|
.BR rm (1)
|
|
|
|
affect the file referred to by
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR slink .
|
2008-06-11 21:25:12 +00:00
|
|
|
|
|
|
|
The \fIsecond rule\fP applies to symbolic links that refer to directories.
|
|
|
|
Symbolic links that refer to directories are never followed by default.
|
|
|
|
This is often referred to as a "physical" walk, as opposed to a "logical"
|
|
|
|
walk (where symbolic links the refer to directories are followed).
|
|
|
|
|
|
|
|
Certain conventions are (should be) followed as consistently as
|
|
|
|
possible by commands that perform file tree walks:
|
|
|
|
.IP * 2
|
2008-06-12 11:52:08 +00:00
|
|
|
A command can be made to follow
|
2008-06-11 21:25:12 +00:00
|
|
|
any symbolic links named on the command line,
|
|
|
|
regardless of the type of file they reference, by specifying the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-H
|
|
|
|
(for "half-logical") flag.
|
2008-06-11 21:25:12 +00:00
|
|
|
This flag is intended to make the command-line name space look
|
|
|
|
like the logical name space.
|
|
|
|
(Note, for commands that do not always do file tree traversals, the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-H
|
2008-06-11 21:25:12 +00:00
|
|
|
flag will be ignored if the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-R
|
2008-06-11 21:25:12 +00:00
|
|
|
flag is not also specified.)
|
|
|
|
|
|
|
|
For example, the command
|
2008-06-26 13:19:40 +00:00
|
|
|
.I "chown\ \-HR user slink"
|
2008-06-11 21:25:12 +00:00
|
|
|
will traverse the file hierarchy rooted in the file pointed to by
|
2008-06-18 09:36:55 +00:00
|
|
|
.IR slink .
|
2008-06-11 21:25:12 +00:00
|
|
|
Note, the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-H
|
2008-06-11 21:25:12 +00:00
|
|
|
is not the same as the previously discussed
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-h
|
2008-06-11 21:25:12 +00:00
|
|
|
flag.
|
|
|
|
The
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-H
|
2008-06-11 21:25:12 +00:00
|
|
|
flag causes symbolic links specified on the command line to be
|
|
|
|
dereferenced for the purposes of both the action to be performed
|
|
|
|
and the tree walk, and it is as if the user had specified the
|
|
|
|
name of the file to which the symbolic link pointed.
|
|
|
|
.IP *
|
|
|
|
A command can be made to
|
|
|
|
follow any symbolic links named on the command line,
|
|
|
|
as well as any symbolic links encountered during the traversal,
|
|
|
|
regardless of the type of file they reference, by specifying the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-L
|
2008-06-11 21:25:12 +00:00
|
|
|
(for "logical") flag.
|
|
|
|
This flag is intended to make the entire name space look like
|
|
|
|
the logical name space.
|
|
|
|
(Note, for commands that do not always do file tree traversals, the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-L
|
2008-06-11 21:25:12 +00:00
|
|
|
flag will be ignored if the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-R
|
2008-06-11 21:25:12 +00:00
|
|
|
flag is not also specified.)
|
|
|
|
|
|
|
|
For example, the command
|
2008-06-26 13:19:40 +00:00
|
|
|
.I "chown\ \-LR user slink"
|
2008-06-18 09:36:55 +00:00
|
|
|
will change the owner of the file referred to by
|
|
|
|
.IR slink .
|
|
|
|
If
|
|
|
|
.I slink
|
|
|
|
refers to a directory,
|
|
|
|
.B chown
|
|
|
|
will traverse the file hierarchy rooted in the directory that it
|
2008-06-11 21:25:12 +00:00
|
|
|
references.
|
|
|
|
In addition, if any symbolic links are encountered in any file tree that
|
2008-06-18 09:36:55 +00:00
|
|
|
.B chown
|
|
|
|
traverses, they will be treated in the same fashion as
|
|
|
|
.IR slink .
|
2008-06-11 21:25:12 +00:00
|
|
|
.IP *
|
|
|
|
A command can be made to
|
|
|
|
provide the default behavior by specifying the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-P
|
2008-06-18 09:36:55 +00:00
|
|
|
(for "physical") flag.
|
2008-06-11 21:25:12 +00:00
|
|
|
This flag is intended to make the entire name space look like the
|
|
|
|
physical name space.
|
|
|
|
.PP
|
|
|
|
For commands that do not by default do file tree traversals, the
|
2008-06-26 12:56:53 +00:00
|
|
|
.IR \-H ,
|
|
|
|
.IR \-L ,
|
2008-06-11 21:25:12 +00:00
|
|
|
and
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-P
|
2008-06-11 21:25:12 +00:00
|
|
|
flags are ignored if the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-R
|
2008-06-11 21:25:12 +00:00
|
|
|
flag is not also specified.
|
|
|
|
In addition, you may specify the
|
2008-06-26 12:56:53 +00:00
|
|
|
.IR \-H ,
|
|
|
|
.IR \-L ,
|
2008-06-11 21:25:12 +00:00
|
|
|
and
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-P
|
2008-06-18 09:36:55 +00:00
|
|
|
options more than once;
|
|
|
|
the last one specified determines the command's behavior.
|
2008-06-11 21:25:12 +00:00
|
|
|
This is intended to permit you to alias commands to behave one way
|
|
|
|
or the other, and then override that behavior on the command line.
|
|
|
|
|
|
|
|
The
|
|
|
|
.BR ls (1)
|
|
|
|
and
|
|
|
|
.BR rm (1)
|
|
|
|
commands have exceptions to these rules:
|
|
|
|
.IP * 2
|
|
|
|
The
|
|
|
|
.BR rm (1)
|
|
|
|
command operates on the symbolic link, and not the file it references,
|
|
|
|
and therefore never follows a symbolic link.
|
|
|
|
The
|
|
|
|
.BR rm (1)
|
|
|
|
command does not support the
|
2008-06-26 12:56:53 +00:00
|
|
|
.IR \-H ,
|
|
|
|
.IR \-L ,
|
2008-06-11 21:25:12 +00:00
|
|
|
or
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-P
|
2008-06-11 21:25:12 +00:00
|
|
|
options.
|
|
|
|
.IP *
|
|
|
|
To maintain compatibility with historic systems,
|
|
|
|
the
|
|
|
|
.BR ls (1)
|
|
|
|
command acts a little differently.
|
|
|
|
If you do not specify the
|
2008-06-26 12:56:53 +00:00
|
|
|
.IR \-F ,
|
|
|
|
.IR \-d
|
2008-06-11 21:25:12 +00:00
|
|
|
or
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-l
|
2008-06-11 21:25:12 +00:00
|
|
|
options,
|
|
|
|
.BR ls (1)
|
|
|
|
will follow symbolic links specified on the command line.
|
|
|
|
If the
|
2008-06-26 12:56:53 +00:00
|
|
|
.I \-L
|
2008-06-11 21:25:12 +00:00
|
|
|
flag is specified,
|
|
|
|
.BR ls (1)
|
|
|
|
follows all symbolic links,
|
|
|
|
regardless of their type,
|
|
|
|
whether specified on the command line or encountered in the tree walk.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR chgrp (1),
|
|
|
|
.BR chmod (1),
|
|
|
|
.BR find (1),
|
|
|
|
.BR ln (1),
|
|
|
|
.BR ls (1),
|
|
|
|
.BR mv (1),
|
|
|
|
.BR rm (1),
|
|
|
|
.BR lchown (2),
|
|
|
|
.BR link (2),
|
|
|
|
.BR lstat (2),
|
|
|
|
.BR readlink (2),
|
|
|
|
.BR rename (2),
|
|
|
|
.BR symlink (2),
|
|
|
|
.BR unlink (2),
|
|
|
|
.BR utimensat (2),
|
2008-06-18 09:36:55 +00:00
|
|
|
.BR lutimes (3),
|
|
|
|
.BR path_resolution (7)
|