lib/libc/sys/link.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)link.2      8.3 (Berkeley) 1/12/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd December 9, 2006
  32 .Dt LINK 2
  33 .Os
  34 .Sh NAME
  35 .Nm link
  36 .Nd make a hard file link
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In unistd.h
  41 .Ft int
  42 .Fn link "const char *name1" "const char *name2"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn link
  46 system call
  47 atomically creates the specified directory entry (hard link)
  48 .Fa name2
  49 with the attributes of the underlying object pointed at by
  50 .Fa name1 .
  51 If the link is successful: the link count of the underlying object
  52 is incremented;
  53 .Fa name1
  54 and
  55 .Fa name2
  56 share equal access and rights
  57 to the
  58 underlying object.
  59 .Pp
  60 If
  61 .Fa name1
  62 is removed, the file
  63 .Fa name2
  64 is not deleted and the link count of the
  65 underlying object is
  66 decremented.
  67 .Pp
  68 The object pointed at by the
  69 .Fa name1
  70 argument
  71 must exist for the hard link to
  72 succeed and
  73 both
  74 .Fa name1
  75 and
  76 .Fa name2
  77 must be in the same file system.
  78 The
  79 .Fa name1
  80 argument
  81 may not be a directory.
  82 .Sh RETURN VALUES
  83 .Rv -std link
  84 .Sh ERRORS
  85 The
  86 .Fn link
  87 system call
  88 will fail and no link will be created if:
  89 .Bl -tag -width Er
  90 .It Bq Er ENOTDIR
  91 A component of either path prefix is not a directory.
  92 .It Bq Er ENAMETOOLONG
  93 A component of either pathname exceeded 255 characters,
  94 or entire length of either path name exceeded 1023 characters.
  95 .It Bq Er ENOENT
  96 A component of either path prefix does not exist.
  97 .It Bq Er EOPNOTSUPP
  98 The file system containing the file named by
  99 .Fa name1
 100 does not support links.
 101 .It Bq Er EMLINK
 102 The link count of the file named by
 103 .Fa name1
 104 would exceed 32767.
 105 .It Bq Er EACCES
 106 A component of either path prefix denies search permission.
 107 .It Bq Er EACCES
 108 The requested link requires writing in a directory with a mode
 109 that denies write permission.
 110 .It Bq Er ELOOP
 111 Too many symbolic links were encountered in translating one of the pathnames.
 112 .It Bq Er ENOENT
 113 The file named by
 114 .Fa name1
 115 does not exist.
 116 .It Bq Er EEXIST
 117 The link named by
 118 .Fa name2
 119 does exist.
 120 .It Bq Er EPERM
 121 The file named by
 122 .Fa name1
 123 is a directory.
 124 .It Bq Er EPERM
 125 The file named by
 126 .Fa name1
 127 has its immutable or append-only flag set, see the
 128 .Xr chflags 2
 129 manual page for more information.
 130 .It Bq Er EPERM
 131 The parent directory of the file named by
 132 .Fa name2
 133 has its immutable flag set.
 134 .It Bq Er EXDEV
 135 The link named by
 136 .Fa name2
 137 and the file named by
 138 .Fa name1
 139 are on different file systems.
 140 .It Bq Er ENOSPC
 141 The directory in which the entry for the new link is being placed
 142 cannot be extended because there is no space left on the file
 143 system containing the directory.
 144 .It Bq Er EDQUOT
 145 The directory in which the entry for the new link
 146 is being placed cannot be extended because the
 147 user's quota of disk blocks on the file system
 148 containing the directory has been exhausted.
 149 .It Bq Er EIO
 150 An I/O error occurred while reading from or writing to
 151 the file system to make the directory entry.
 152 .It Bq Er EROFS
 153 The requested link requires writing in a directory on a read-only file
 154 system.
 155 .It Bq Er EFAULT
 156 One of the pathnames specified
 157 is outside the process's allocated address space.
 158 .El
 159 .Sh SEE ALSO
 160 .Xr chflags 2 ,
 161 .Xr readlink 2 ,
 162 .Xr symlink 2 ,
 163 .Xr unlink 2
 164 .Sh STANDARDS
 165 The
 166 .Fn link
 167 system call is expected to conform to
 168 .St -p1003.1-90 .
 169 .Sh HISTORY
 170 The
 171 .Fn link
 172 function appeared in
 173 .At v7 .
 174 .Pp
 175 The
 176 .Fn link
 177 system call traditionally allows the super-user to link directories which
 178 corrupts the file system coherency.
 179 This implementation no longer permits
 180 it.