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