lib/libc/sys/symlink.2

   1 .\" Copyright (c) 1983, 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 .\"     @(#)symlink.2   8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/sys/symlink.2,v 1.23 2008/04/16 13:03:12 kib Exp $
  30 .\"
  31 .Dd August 6, 2010
  32 .Dt SYMLINK 2
  33 .Os
  34 .Sh NAME
  35 .Nm symlink ,
  36 .Nm symlinkat
  37 .Nd make symbolic link to a file
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft int
  43 .Fn symlink "const char *name1" "const char *name2"
  44 .Ft int
  45 .Fn symlinkat "const char *name1" "int fd" "const char *name2"
  46 .Sh DESCRIPTION
  47 A symbolic link
  48 .Fa name2
  49 is created to
  50 .Fa name1
  51 .Fa ( name2
  52 is the name of the
  53 file created,
  54 .Fa name1
  55 is the string
  56 used in creating the symbolic link).
  57 Either name may be an arbitrary path name; the files need not
  58 be on the same file system.
  59 .Pp
  60 The
  61 .Fn symlinkat
  62 system call is equivalent to
  63 .Fn symlink
  64 except in the case where
  65 .Fa name2
  66 specifies a relative path.
  67 In this case the symbolic link is created relative to the directory
  68 associated with the file descriptor
  69 .Fa fd
  70 instead of the current working directory.
  71 If
  72 .Fn symlinkat
  73 is passed the special value
  74 .Dv AT_FDCWD
  75 in the
  76 .Fa fd
  77 parameter, the current working directory is used and the behavior is
  78 identical to a call to
  79 .Fn symlink .
  80 .Sh RETURN VALUES
  81 .Rv -std symlink
  82 .Sh ERRORS
  83 The symbolic link succeeds unless:
  84 .Bl -tag -width Er
  85 .It Bq Er ENOTDIR
  86 A component of the
  87 .Fa name2
  88 path prefix is not a directory.
  89 .It Bq Er ENAMETOOLONG
  90 A component of the
  91 .Fa name2
  92 pathname exceeded 255 characters,
  93 or the entire length of either path name exceeded 1023 characters.
  94 .It Bq Er ENOENT
  95 A component of the
  96 .Fa name2
  97 path prefix does not exist.
  98 .It Bq Er EACCES
  99 A component of the
 100 .Fa name2
 101 path prefix denies search permission, or write permission is denied on the
 102 parent directory of the file to be created.
 103 .It Bq Er ELOOP
 104 Too many symbolic links were encountered in translating the
 105 .Fa name2
 106 path name.
 107 .It Bq Er EEXIST
 108 The path name pointed at by the
 109 .Fa name2
 110 argument
 111 already exists.
 112 .It Bq Er EPERM
 113 The parent directory of the file named by
 114 .Fa name2
 115 has its immutable flag set, see the
 116 .Xr chflags 2
 117 manual page for more information.
 118 .It Bq Er EIO
 119 An I/O error occurred while making the directory entry for
 120 .Fa name2 ,
 121 or allocating the inode for
 122 .Fa name2 ,
 123 or writing out the link contents of
 124 .Fa name2 .
 125 .It Bq Er EROFS
 126 The file
 127 .Fa name2
 128 would reside on a read-only file system.
 129 .It Bq Er ENOSPC
 130 The directory in which the entry for the new symbolic link is being placed
 131 cannot be extended because there is no space left on the file
 132 system containing the directory.
 133 .It Bq Er ENOSPC
 134 The new symbolic link cannot be created because
 135 there is no space left on the file
 136 system that will contain the symbolic link.
 137 .It Bq Er ENOSPC
 138 There are no free inodes on the file system on which the
 139 symbolic link is being created.
 140 .It Bq Er EDQUOT
 141 The directory in which the entry for the new symbolic 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 EDQUOT
 146 The new symbolic link cannot be created because the user's
 147 quota of disk blocks on the file system that will
 148 contain the symbolic link has been exhausted.
 149 .It Bq Er EDQUOT
 150 The user's quota of inodes on the file system on
 151 which the symbolic link is being created has been exhausted.
 152 .It Bq Er EIO
 153 An I/O error occurred while making the directory entry or allocating the inode.
 154 .It Bq Er EFAULT
 155 The
 156 .Fa name1
 157 or
 158 .Fa name2
 159 argument
 160 points outside the process's allocated address space.
 161 .El
 162 .Pp
 163 In addition to the errors returned by the
 164 .Fn symlink ,
 165 the
 166 .Fn symlinkat
 167 may fail if:
 168 .Bl -tag -width Er
 169 .It Bq Er EBADF
 170 The
 171 .Fa name2
 172 argument does not specify an absolute path and the
 173 .Fa fd
 174 argument is neither
 175 .Dv AT_FDCWD
 176 nor a valid file descriptor open for searching.
 177 .It Bq Er ENOTDIR
 178 The
 179 .Fa name2
 180 argument is not an absolute path and
 181 .Fa fd
 182 is neither
 183 .Dv AT_FDCWD
 184 nor a file descriptor associated with a directory.
 185 .El
 186 .Sh SEE ALSO
 187 .Xr ln 1 ,
 188 .Xr chflags 2 ,
 189 .Xr link 2 ,
 190 .Xr lstat 2 ,
 191 .Xr readlink 2 ,
 192 .Xr unlink 2 ,
 193 .Xr symlink 7
 194 .Sh STANDARDS
 195 The
 196 .Fn symlinkat
 197 system call follows The Open Group Extended API Set 2 specification.
 198 .Sh HISTORY
 199 The
 200 .Fn symlink
 201 system call appeared in
 202 .Bx 4.2 .
 203 The
 204 .Fn symlinkat
 205 system call appeared in
 206 .Dx 2.7 .