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