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