Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SYMLINK(7)		   Linux Programmer's Manual		    SYMLINK(7)

NAME
       symlink - symbolic link handling

SYMBOLIC LINK HANDLING
       Symbolic	 links	are files that act as pointers to other	files.	To un-
       derstand	their behavior,	you must first understand how hard links work.

       A hard link to a	file is	indistinguishable from the original  file  be-
       cause it	is a reference to the object underlying	the original filename.
       (To be precise: each of the hard	links to a file	is a reference to  the
       same  i-node number, where an i-node number is an index into the	i-node
       table, which contains metadata about all	files on a file	 system.   See
       stat(2).)  Changes to a file are	independent of the name	used to	refer-
       ence the	file.  Hard links may not refer	to directories (to prevent the
       possibility  of	loops within the file system tree, which would confuse
       many programs) and may not refer	to files  on  different	 file  systems
       (because	i-node numbers are not unique across file systems).

       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.
       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 file system boundaries.

       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 to be a dangling link.

       Because	a  symbolic link and its referenced object coexist in the file
       system name space, confusion can	arise in  distinguishing  between  the
       link itself and the referenced object.  On historical systems, commands
       and system calls	adopted	their  own  link-following  conventions	 in  a
       somewhat	 ad-hoc	 fashion.   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.

   Symbolic link ownership, permissions, and timestamps
       The owner and group of an existing symbolic link	can be	changed	 using
       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 stat(2)).

       The last	access and last	modification timestamps	of a symbolic link can
       be changed using	utimensat(2) or	lutimes(3).

       On Linux, the permissions of a symbolic link are	not used in any	opera-
       tions;  the  permissions	 are always 0777 (read,	write, and execute for
       all user	categories), and can't be changed.

   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, an	application or system call is said to follow the  link.	  Sym-
       bolic  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:

       1. Symbolic links used as filename arguments for	system calls.

       2. Symbolic links specified as command-line arguments to	utilities that
	  are not traversing a file tree.

       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).

   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 ex-
       ample, if there were a symbolic link slink  which  pointed  to  a  file
       named  afile, the system	call open("slink" ...) would return a file de-
       scriptor	referring to the file afile.

       Various system calls do not follow links, and operate on	 the  symbolic
       link  itself.   They  are: lchown(2), lgetxattr(2), llistxattr(2), lre-
       movexattr(2), lsetxattr(2), lstat(2), readlink(2), rename(2), rmdir(2),
       and  unlink(2).	 Certain other system calls optionally follow symbolic
       links.  They are:  faccessat(2),	 fchownat(2),  fstatat(2),  linkat(2),
       open(2),	 openat(2),  and  utimensat(2);	see their manual pages for de-
       tails.  Because remove(3) is an alias for unlink(2), that library func-
       tion  also does not follow symbolic links.  When	rmdir(2) is applied to
       a symbolic link,	it fails with the error	ENOTDIR.  The link(2) warrants
       special	discussion.  POSIX.1-2001 specifies that link(2) should	deref-
       erence oldpath if it is a symbolic link.	 However, Linux	 does  not  do
       this.   (By default Solaris is the same,	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.

   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 slink which
       pointed	to a file named	afile, the command cat slink would display the
       contents	of the file afile.

       It is important to realize that this rule includes commands  which  may
       optionally  traverse  file  trees,  e.g., the command chown file	is in-
       cluded in this rule, while the command chown -R file, 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
       chown slink change the ownership	of the file that slink is, whether  it
       is  a symbolic link or not, the -h option should	be used.  In the above
       example,	chown root slink would change the ownership of	the  file  re-
       ferred  to  by slink, while chown -h root slink would change the	owner-
       ship of slink itself.

       There are some exceptions to this rule:

       * The mv(1) and 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 work-
	 ing, since the	path may no longer be correct.)

       * The ls(1) command is also an exception	to this	rule.  For compatibil-
	 ity with historic systems (when ls(1) is not doing a tree walk, i.e.,
	 the -R	option is not specified), the ls(1) command  follows  symbolic
	 links	named  as arguments if the -H or -L option is specified, or if
	 the -F, -d, or	-l options are not specified.  (The ls(1)  command  is
	 the only command where	the -H and -L options affect its behavior even
	 though	it is not doing	a walk of a file tree.)

       * The file(1) command is	also an	exception to this rule.	  The  file(1)
	 command  does not follow symbolic links named as argument by default.
	 The file(1) command does follow symbolic links	named as  argument  if
	 the -L	option is specified.

   Commands traversing a file tree
       The following commands either optionally	or always traverse file	trees:
       chgrp(1), chmod(1), chown(1), cp(1),  du(1),  find(1),  ls(1),  pax(1),
       rm(1), and 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  first  rule	 applies  to symbolic links that reference files other
       than directories.  Operations that apply	to  symbolic  links  are  per-
       formed on the links themselves, but otherwise the links are ignored.

       The  command  rm	-r  slink  directory will remove slink,	as well	as any
       symbolic	links encountered in the tree traversal	of directory,  because
       symbolic	 links	may be removed.	 In no case will rm(1) affect the file
       referred	to by slink.

       The second rule 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	"logi-
       cal" walk (where	symbolic links the refer to directories	are followed).

       Certain	conventions are	(should	be) followed as	consistently as	possi-
       ble by commands that perform file tree walks:

       * A command can be made to follow any symbolic links named on the  com-
	 mand line, regardless of the type of file they	reference, by specify-
	 ing the -H (for "half-logical") flag.	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 -H  flag
	 will be ignored if the	-R flag	is not also specified.)

	 For  example, the command chown -HR user slink	will traverse the file
	 hierarchy rooted in the file pointed to by slink.  Note,  the	-H  is
	 not the same as the previously	discussed -h flag.  The	-H 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.

       * A  command can	be made	to follow any symbolic links named on the com-
	 mand line, as well as any symbolic links encountered during the  tra-
	 versal,  regardless of	the type of file they reference, by specifying
	 the -L	(for "logical")	flag.  This flag is intended to	make  the  en-
	 tire  name  space  look like the logical name space.  (Note, for com-
	 mands that do not always do file tree traversals, the -L flag will be
	 ignored if the	-R flag	is not also specified.)

	 For  example,	the command chown -LR user slink will change the owner
	 of the	file referred to by slink.  If slink refers  to	 a  directory,
	 chown	will  traverse the file	hierarchy rooted in the	directory that
	 it references.	 In addition, if any symbolic links are	encountered in
	 any  file tree	that chown traverses, they will	be treated in the same
	 fashion as slink.

       * A command can be made to provide the default behavior	by  specifying
	 the  -P (for "physical") flag.	 This flag is intended to make the en-
	 tire name space look like the physical	name space.

       For commands that do not	by default do file tree	 traversals,  the  -H,
       -L,  and	-P flags are ignored if	the -R flag is not also	specified.  In
       addition, you may specify the -H, -L, and -P options  more  than	 once;
       the  last one specified determines the command's	behavior.  This	is in-
       tended to permit	you to alias commands to behave	one way	or the	other,
       and then	override that behavior on the command line.

       The ls(1) and rm(1) commands have exceptions to these rules:

       * The  rm(1) command operates on	the symbolic link, and not the file it
	 references, and therefore never follows a symbolic link.   The	 rm(1)
	 command does not support the -H, -L, or -P options.

       * To  maintain  compatibility  with historic systems, the ls(1) command
	 acts a	little differently.  If	you do not specify the -F,  -d	or  -l
	 options,  ls(1)  will	follow symbolic	links specified	on the command
	 line.	If the -L flag is specified, ls(1) follows all symbolic	links,
	 regardless  of	 their	type, whether specified	on the command line or
	 encountered in	the tree walk.

SEE ALSO
       chgrp(1), chmod(1), find(1), ln(1),  ls(1),  mv(1),  rm(1),  lchown(2),
       link(2),	 lstat(2), readlink(2),	rename(2), symlink(2), unlink(2), uti-
       mensat(2), lutimes(3), path_resolution(7)

COLOPHON
       This page is part of release 3.53 of the	Linux  man-pages  project.   A
       description  of	the project, and information about reporting bugs, can
       be found	at http://www.kernel.org/doc/man-pages/.

Linux				  2008-06-18			    SYMLINK(7)

NAME | SYMBOLIC LINK HANDLING | SEE ALSO | COLOPHON

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=symlink&sektion=7&manpath=CentOS+7.1>

home | help