man2/symlink.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\"             and Copyright (C) 2006, 2014 Michael Kerrisk
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" Modified 1993-07-24 by Rik Faith
   8 .\" Modified 1996-04-26 by Nick Duffek <nsd@bbc.com>
   9 .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
  10 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  11 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  12 .\"
  13 .TH SYMLINK 2 2021-08-27 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  14 .SH NAME
  15 symlink, symlinkat \- make a new name for a file
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <unistd.h>
  22 .PP
  23 .BI "int symlink(const char *" target ", const char *" linkpath );
  24 .PP
  25 .BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
  26 .B #include <unistd.h>
  27 .PP
  28 .BI "int symlinkat(const char *" target ", int " newdirfd \
  29 ", const char *" linkpath );
  30 .PP
  31 .fi
  32 .RS -4
  33 Feature Test Macro Requirements for glibc (see
  34 .BR feature_test_macros (7)):
  35 .RE
  36 .PP
  37 .BR symlink ():
  38 .nf
  39     _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
  40 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  41         || /* Glibc <= 2.19: */ _BSD_SOURCE
  42 .fi
  43 .PP
  44 .BR symlinkat ():
  45 .nf
  46     Since glibc 2.10:
  47         _POSIX_C_SOURCE >= 200809L
  48     Before glibc 2.10:
  49         _ATFILE_SOURCE
  50 .fi
  51 .SH DESCRIPTION
  52 .BR symlink ()
  53 creates a symbolic link named
  54 .I linkpath
  55 which contains the string
  56 .IR target .
  57 .PP
  58 Symbolic links are interpreted at run time as if the contents of the
  59 link had been substituted into the path being followed to find a file or
  60 directory.
  61 .PP
  62 Symbolic links may contain
  63 .I ..
  64 path components, which (if used at the start of the link) refer to the
  65 parent directories of that in which the link resides.
  66 .PP
  67 A symbolic link (also known as a soft link) may point to an existing
  68 file or to a nonexistent one; the latter case is known as a dangling
  69 link.
  70 .PP
  71 The permissions of a symbolic link are irrelevant; the ownership is
  72 ignored when following the link
  73 (except when the
  74 .I protected_symlinks
  75 feature in enabled, as explained in
  76 .BR proc (5)),
  77 but is checked when removal or
  78 renaming of the link is requested and the link is in a directory with
  79 the sticky bit
  80 .RB ( S_ISVTX )
  81 set.
  82 .PP
  83 If
  84 .I linkpath
  85 exists, it will
  86 .I not
  87 be overwritten.
  88 .SS symlinkat()
  89 The
  90 .BR symlinkat ()
  91 system call operates in exactly the same way as
  92 .BR symlink (),
  93 except for the differences described here.
  94 .PP
  95 If the pathname given in
  96 .I linkpath
  97 is relative, then it is interpreted relative to the directory
  98 referred to by the file descriptor
  99 .I newdirfd
 100 (rather than relative to the current working directory of
 101 the calling process, as is done by
 102 .BR symlink ()
 103 for a relative pathname).
 104 .PP
 105 If
 106 .I linkpath
 107 is relative and
 108 .I newdirfd
 109 is the special value
 110 .BR AT_FDCWD ,
 111 then
 112 .I linkpath
 113 is interpreted relative to the current working
 114 directory of the calling process (like
 115 .BR symlink ()).
 116 .PP
 117 If
 118 .I linkpath
 119 is absolute, then
 120 .I newdirfd
 121 is ignored.
 122 .PP
 123 See
 124 .BR openat (2)
 125 for an explanation of the need for
 126 .BR symlinkat ().
 127 .SH RETURN VALUE
 128 On success, zero is returned.
 129 On error, \-1 is returned, and
 130 .I errno
 131 is set to indicate the error.
 132 .SH ERRORS
 133 .TP
 134 .B EACCES
 135 Write access to the directory containing
 136 .I linkpath
 137 is denied, or one of the directories in the path prefix of
 138 .I linkpath
 139 did not allow search permission.
 140 (See also
 141 .BR path_resolution (7).)
 142 .TP
 143 .B EBADF
 144 .RB ( symlinkat ())
 145 .I linkpath
 146 is relative but
 147 .I newdirfd
 148 is neither
 149 .B AT_FDCWD
 150 nor a valid file descriptor.
 151 .TP
 152 .B EDQUOT
 153 The user's quota of resources on the filesystem has been exhausted.
 154 The resources could be inodes or disk blocks, depending on the filesystem
 155 implementation.
 156 .TP
 157 .B EEXIST
 158 .I linkpath
 159 already exists.
 160 .TP
 161 .B EFAULT
 162 .IR target " or " linkpath " points outside your accessible address space."
 163 .TP
 164 .B EIO
 165 An I/O error occurred.
 166 .TP
 167 .B ELOOP
 168 Too many symbolic links were encountered in resolving
 169 .IR linkpath .
 170 .TP
 171 .B ENAMETOOLONG
 172 .IR target " or " linkpath " was too long."
 173 .TP
 174 .B ENOENT
 175 A directory component in
 176 .I linkpath
 177 does not exist or is a dangling symbolic link, or
 178 .I target
 179 or
 180 .I linkpath
 181 is an empty string.
 182 .TP
 183 .B ENOENT
 184 .RB ( symlinkat ())
 185 .I linkpath
 186 is a relative pathname and
 187 .I newdirfd
 188 refers to a directory that has been deleted.
 189 .TP
 190 .B ENOMEM
 191 Insufficient kernel memory was available.
 192 .TP
 193 .B ENOSPC
 194 The device containing the file has no room for the new directory
 195 entry.
 196 .TP
 197 .B ENOTDIR
 198 A component used as a directory in
 199 .I linkpath
 200 is not, in fact, a directory.
 201 .TP
 202 .B ENOTDIR
 203 .RB ( symlinkat ())
 204 .I linkpath
 205 is relative and
 206 .I newdirfd
 207 is a file descriptor referring to a file other than a directory.
 208 .TP
 209 .B EPERM
 210 The filesystem containing
 211 .I linkpath
 212 does not support the creation of symbolic links.
 213 .TP
 214 .B EROFS
 215 .I linkpath
 216 is on a read-only filesystem.
 217 .SH VERSIONS
 218 .BR symlinkat ()
 219 was added to Linux in kernel 2.6.16;
 220 library support was added to glibc in version 2.4.
 221 .SH STANDARDS
 222 .BR symlink ():
 223 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
 224 .\" SVr4 documents additional error codes EDQUOT and ENOSYS.
 225 .\" See
 226 .\" .BR open (2)
 227 .\" re multiple files with the same name, and NFS.
 228 .PP
 229 .BR symlinkat ():
 230 POSIX.1-2008.
 231 .SH NOTES
 232 No checking of
 233 .I target
 234 is done.
 235 .PP
 236 Deleting the name referred to by a symbolic link will actually delete the
 237 file (unless it also has other hard links).
 238 If this behavior is not desired, use
 239 .BR link (2).
 240 .SS Glibc notes
 241 On older kernels where
 242 .BR symlinkat ()
 243 is unavailable, the glibc wrapper function falls back to the use of
 244 .BR symlink ().
 245 When
 246 .I linkpath
 247 is a relative pathname,
 248 glibc constructs a pathname based on the symbolic link in
 249 .I /proc/self/fd
 250 that corresponds to the
 251 .I newdirfd
 252 argument.
 253 .SH SEE ALSO
 254 .BR ln (1),
 255 .BR namei (1),
 256 .BR lchown (2),
 257 .BR link (2),
 258 .BR lstat (2),
 259 .BR open (2),
 260 .BR readlink (2),
 261 .BR rename (2),
 262 .BR unlink (2),
 263 .BR path_resolution (7),
 264 .BR symlink (7)