lib/libc/sys/link.2

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