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

FreeBSD Manual Pages


home | help
LINK(3P)		   POSIX Programmer's Manual		      LINK(3P)

       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface	may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

       link - link to a	file

       #include	<unistd.h>

       int link(const char *path1, const char *path2);

       The link() function shall create	a new link (directory entry)  for  the
       existing	file, path1.

       The  path1  argument points to a	pathname naming	an existing file.  The
       path2 argument points to	a pathname naming the new directory  entry  to
       be  created. The	link() function	shall atomically create	a new link for
       the existing file and the link count of the file	shall  be  incremented
       by one.

       If  path1  names	 a directory, link() shall fail	unless the process has
       appropriate privileges and the implementation supports using link()  on

       Upon  successful	 completion, link() shall mark for update the st_ctime
       field of	the file. Also,	the st_ctime and st_mtime fields of the	direc-
       tory that contains the new entry	shall be marked	for update.

       If  link()  fails,  no  link shall be created and the link count	of the
       file shall remain unchanged.

       The implementation may require that the calling process has  permission
       to access the existing file.

       Upon successful completion, 0 shall be returned.	Otherwise, -1 shall be
       returned	and errno set to indicate the error.

       The link() function shall fail if:

       EACCES A	component of either path prefix	denies search  permission,  or
	      the  requested  link requires writing in a directory that	denies
	      write permission,	or the calling process does not	 have  permis-
	      sion  to	access	the  existing file and this is required	by the

       EEXIST The path2	argument resolves to an	existing file or refers	 to  a
	      symbolic link.

       ELOOP  A	loop exists in symbolic	links encountered during resolution of
	      the path1	or path2 argument.

       EMLINK The number of links to the file  named  by  path1	 would	exceed

	      The  length of the path1 or path2	argument exceeds {PATH_MAX} or
	      a	pathname component is longer than {NAME_MAX}.

       ENOENT A	component of either path prefix	does not exist;	the file named
	      by  path1	 does  not exist; or path1 or path2 points to an empty

       ENOSPC The directory to contain the link	cannot be extended.

	      A	component of either path prefix	is not a directory.

       EPERM  The file named by	path1 is a directory and  either  the  calling
	      process  does not	have appropriate privileges or the implementa-
	      tion prohibits using link() on directories.

       EROFS  The requested link requires writing in a directory  on  a	 read-
	      only file	system.

       EXDEV  The  link	named by path2 and the file named by path1 are on dif-
	      ferent file systems and  the  implementation  does  not  support
	      links between file systems.

       EXDEV  path1 refers to a	named STREAM.

       The link() function may fail if:

       ELOOP  More  than  {SYMLOOP_MAX}	symbolic links were encountered	during
	      resolution of the	path1 or path2 argument.

	      As a result of encountering a symbolic link in resolution	of the
	      path1  or	path2 argument,	the length of the substituted pathname
	      string exceeded {PATH_MAX}.

       The following sections are informative.

   Creating a Link to a	File
       The following example shows how to  create  a  link  to	a  file	 named
       /home/cnd/mod1  by creating a new directory entry named /modules/pass1.

	      #include <unistd.h>

	      char *path1 = "/home/cnd/mod1";
	      char *path2 = "/modules/pass1";
	      int   status;
	      status = link (path1, path2);

   Creating a Link to a	File Within a Program
       In the  following  program  example,  the  link()  function  links  the
       /etc/passwd  file  (defined as PASSWDFILE) to a file named /etc/opasswd
       (defined	as SAVEFILE), which is used to save the	current	password file.
       Then, after removing the	current	password file (defined as PASSWDFILE),
       the new password	file is	saved as the current password file  using  the
       link() function again.

	      #include <unistd.h>

	      #define LOCKFILE "/etc/ptmp"
	      #define PASSWDFILE "/etc/passwd"
	      #define SAVEFILE "/etc/opasswd"
	      /* Save current password file */

	      /* Remove	current	password file. */
	      unlink (PASSWDFILE);

	      /* Save new password file	as current password file. */

       Some implementations do allow links between file	systems.

       Linking	to a directory is restricted to	the superuser in most histori-
       cal implementations because this	capability may produce	loops  in  the
       file  hierarchy	or  otherwise corrupt the file system.	This volume of
       IEEE Std	1003.1-2001 continues that philosophy  by  prohibiting	link()
       and unlink() from doing this. Other functions could do it if the	imple-
       mentor designed such an extension.

       Some historical implementations allow linking  of  files	 on  different
       file  systems.  Wording	was  added  to	explicitly allow this optional

       The exception for cross-file system links is intended to	apply only  to
       links that are programmatically indistinguishable from "hard" links.


       symlink(),     unlink(),	    the	   Base	   Definitions	  volume    of
       IEEE Std	1003.1-2001, _unistd.h_

       Portions	of this	text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for	Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of	any discrepancy	between	this version and the original IEEE and
       The Open	Group Standard,	the original IEEE and The Open Group  Standard
       is  the	referee	document. The original Standard	can be obtained	online
       at .

IEEE/The Open Group		     2003			      LINK(3P)


Want to link to this manual page? Use this URL:

home | help