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