1.\" $OpenBSD: symlink.2,v 1.13 2011/07/18 23:04:40 matthew Exp $ 2.\" $NetBSD: symlink.2,v 1.7 1995/02/27 12:38:34 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)symlink.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: July 18 2011 $ 34.Dt SYMLINK 2 35.Os 36.Sh NAME 37.Nm symlink 38.Nd make symbolic link to a file 39.Sh SYNOPSIS 40.Fd #include <fcntl.h> 41.Fd #include <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.Pf ( 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, and the file specified by 59.Fa name1 60need not exist at all. 61.Pp 62The 63.Fn symlinkat 64function is equivalent to 65.Fn symlink 66except that where 67.Fa name2 68specifies a relative path, 69the newly created symbolic link is created relative to 70the directory associated with file descriptor 71.Fa fd 72instead of the current working directory. 73.Pp 74If 75.Fn symlinkat 76is passed the special value 77.Dv AT_FDCWD 78(defined in 79.In fcntl.h ) 80in the 81.Fa fd 82parameter, the current working directory is used 83and the behavior is identical to a call to 84.Fn symlink . 85.Sh RETURN VALUES 86Upon successful completion, a zero value is returned. 87If an error occurs, the error code is stored in 88.Va errno 89and a \-1 value is returned. 90.Sh ERRORS 91The symbolic link succeeds unless: 92.Bl -tag -width Er 93.It Bq Er ENOTDIR 94A component of the 95.Fa name2 96prefix is not a directory. 97.It Bq Er ENAMETOOLONG 98A component of a pathname exceeded 99.Dv {NAME_MAX} 100characters, or an entire path name exceeded 101.Dv {PATH_MAX} 102characters. 103.It Bq Er ENOENT 104The named file does not exist. 105.It Bq Er EACCES 106A component of the 107.Fa name2 108path prefix denies search permission. 109.It Bq Er ELOOP 110Too many symbolic links were encountered in translating the pathname. 111.It Bq Er EEXIST 112.Fa name2 113already exists. 114.It Bq Er EIO 115An I/O error occurred while making the directory entry for 116.Fa name2 , 117or allocating the inode for 118.Fa name2 , 119or writing out the link contents of 120.Fa name2 . 121.It Bq Er EROFS 122The file 123.Fa name2 124would reside on a read-only file system. 125.It Bq Er ENOSPC 126The directory in which the entry for the new symbolic link is being placed 127cannot be extended because there is no space left on the file 128system containing the directory. 129.It Bq Er ENOSPC 130The new symbolic link cannot be created because there 131is no space left on the file 132system that will contain the symbolic link. 133.It Bq Er ENOSPC 134There are no free inodes on the file system on which the 135symbolic link is being created. 136.It Bq Er EDQUOT 137The directory in which the entry for the new symbolic link 138is being placed cannot be extended because the 139user's quota of disk blocks on the file system 140containing the directory has been exhausted. 141.It Bq Er EDQUOT 142The new symbolic link cannot be created because the user's 143quota of disk blocks on the file system that will 144contain the symbolic link has been exhausted. 145.It Bq Er EDQUOT 146The user's quota of inodes on the file system on 147which the symbolic link is being created has been exhausted. 148.It Bq Er EIO 149An I/O error occurred while making the directory entry or allocating the inode. 150.It Bq Er EFAULT 151.Fa name1 152or 153.Fa name2 154points outside the process's allocated address space. 155.El 156.Pp 157Additionally, 158.Fn symlinkat 159will fail if: 160.Bl -tag -width Er 161.It Bq Er EBADF 162The 163.Fa name2 164argument does not specify an absolute path and the 165.Fa fd 166argument is neither 167.Dv AT_FDCWD 168nor a valid file descriptor open for reading. 169.El 170.Sh SEE ALSO 171.Xr ln 1 , 172.Xr link 2 , 173.Xr readlink 2 , 174.Xr unlink 2 , 175.Xr symlink 7 176.Sh STANDARDS 177The 178.Fn symlink 179and 180.Fn symlinkat 181functions conform to 182.St -p1003.1-2008 . 183.Sh HISTORY 184The 185.Fn symlink 186function call appeared in 187.Bx 4.2 . 188The 189.Fn symlinkat 190function call appeared in 191.Ox 5.0 . 192