Add some more *at() system calls.
[dragonfly.git] / lib / libc / sys / symlink.2
CommitLineData
984263bc
MD
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.
984263bc
MD
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
6d98f93c 29.\" $FreeBSD: src/lib/libc/sys/symlink.2,v 1.23 2008/04/16 13:03:12 kib Exp $
984263bc 30.\"
6d98f93c 31.Dd August 6, 2010
984263bc
MD
32.Dt SYMLINK 2
33.Os
34.Sh NAME
6d98f93c
SW
35.Nm symlink ,
36.Nm symlinkat
984263bc
MD
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"
6d98f93c
SW
44.Ft int
45.Fn symlinkat "const char *name1" "int fd" "const char *name2"
984263bc
MD
46.Sh DESCRIPTION
47A symbolic link
48.Fa name2
49is created to
50.Fa name1
6d98f93c 51.Fa ( name2
984263bc
MD
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.
6d98f93c
SW
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 .
984263bc
MD
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
6d98f93c 88path prefix is not a directory.
984263bc 89.It Bq Er ENAMETOOLONG
6d98f93c
SW
90A component of the
91.Fa name2
92pathname exceeded 255 characters,
984263bc
MD
93or the entire length of either path name exceeded 1023 characters.
94.It Bq Er ENOENT
6d98f93c
SW
95A component of the
96.Fa name2
97path prefix does not exist.
984263bc
MD
98.It Bq Er EACCES
99A component of the
100.Fa name2
6d98f93c
SW
101path prefix denies search permission, or write permission is denied on the
102parent directory of the file to be created.
984263bc 103.It Bq Er ELOOP
6d98f93c
SW
104Too many symbolic links were encountered in translating the
105.Fa name2
106path name.
984263bc 107.It Bq Er EEXIST
6d98f93c
SW
108The path name pointed at by the
109.Fa name2
110argument
984263bc 111already exists.
6d98f93c
SW
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.
984263bc
MD
118.It Bq Er EIO
119An I/O error occurred while making the directory entry for
120.Fa name2 ,
121or allocating 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 EIO
153An I/O error occurred while making the directory entry or allocating the inode.
154.It Bq Er EFAULT
6d98f93c
SW
155The
156.Fa name1
984263bc
MD
157or
158.Fa name2
6d98f93c 159argument
984263bc
MD
160points outside the process's allocated address space.
161.El
6d98f93c
SW
162.Pp
163In addition to the errors returned by the
164.Fn symlink ,
165the
166.Fn symlinkat
167may fail if:
168.Bl -tag -width Er
169.It Bq Er EBADF
170The
171.Fa name2
172argument does not specify an absolute path and the
173.Fa fd
174argument is neither
175.Dv AT_FDCWD
176nor a valid file descriptor open for searching.
177.It Bq Er ENOTDIR
178The
179.Fa name2
180argument is not an absolute path and
181.Fa fd
182is neither
183.Dv AT_FDCWD
184nor a file descriptor associated with a directory.
185.El
984263bc
MD
186.Sh SEE ALSO
187.Xr ln 1 ,
6d98f93c 188.Xr chflags 2 ,
984263bc
MD
189.Xr link 2 ,
190.Xr lstat 2 ,
191.Xr readlink 2 ,
192.Xr unlink 2 ,
193.Xr symlink 7
6d98f93c
SW
194.Sh STANDARDS
195The
196.Fn symlinkat
197system call follows The Open Group Extended API Set 2 specification.
984263bc
MD
198.Sh HISTORY
199The
200.Fn symlink
6d98f93c 201system call appeared in
984263bc 202.Bx 4.2 .
6d98f93c
SW
203The
204.Fn symlinkat
205system call appeared in
206.Dx 2.7 .