.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
+.\" and Copyright (C) 2006, 2014 Michael Kerrisk
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.TH SYMLINK 2 2013-01-27 "Linux" "Linux Programmer's Manual"
+.TH SYMLINK 2 2014-08-19 "Linux" "Linux Programmer's Manual"
.SH NAME
-symlink \- make a new name for a file
+symlink, symlinkat \- make a new name for a file
.SH SYNOPSIS
+.nf
.B #include <unistd.h>
.sp
-.BI "int symlink(const char *" oldpath ", const char *" newpath );
+.BI "int symlink(const char *" target ", const char *" linkpath );
.sp
+.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
+.B #include <unistd.h>
+.sp
+.BI "int symlinkat(const char *" target ", int " newdirfd \
+", const char *" linkpath );
+.sp
+.fi
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\ >=\ 200112L
.RE
+.sp
+.BR symlinkat ():
+.PD 0
+.ad l
+.RS 4
+.TP 4
+Since glibc 2.10:
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+.TP
+Before glibc 2.10:
+_ATFILE_SOURCE
+.RE
.ad b
+.PD
.SH DESCRIPTION
.BR symlink ()
creates a symbolic link named
-.I newpath
+.I linkpath
which contains the string
-.IR oldpath .
+.IR target .
Symbolic links are interpreted at run time as if the contents of the
link had been substituted into the path being followed to find a file or
set.
If
-.I newpath
-exists it will
+.I linkpath
+exists, it will
.I not
be overwritten.
+.SS symlinkat()
+The
+.BR symlinkat ()
+system call operates in exactly the same way as
+.BR symlink (),
+except for the differences described here.
+
+If the pathname given in
+.I linkpath
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I newdirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR symlink ()
+for a relative pathname).
+
+If
+.I linkpath
+is relative and
+.I newdirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I linkpath
+is interpreted relative to the current working
+directory of the calling process (like
+.BR symlink ()).
+
+If
+.I linkpath
+is absolute, then
+.I newdirfd
+is ignored.
.SH RETURN VALUE
On success, zero is returned.
On error, \-1 is returned, and
.TP
.B EACCES
Write access to the directory containing
-.I newpath
+.I linkpath
is denied, or one of the directories in the path prefix of
-.I newpath
+.I linkpath
did not allow search permission.
(See also
.BR path_resolution (7).)
.TP
.B EDQUOT
-The user's quota of resources on the file system has been exhausted.
-The resources could be inodes or disk blocks, depending on the file
-system implementation.
+The user's quota of resources on the filesystem has been exhausted.
+The resources could be inodes or disk blocks, depending on the filesystem
+implementation.
.TP
.B EEXIST
-.I newpath
+.I linkpath
already exists.
.TP
.B EFAULT
-.IR oldpath " or " newpath " points outside your accessible address space."
+.IR target " or " linkpath " points outside your accessible address space."
.TP
.B EIO
An I/O error occurred.
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR newpath .
+.IR linkpath .
.TP
.B ENAMETOOLONG
-.IR oldpath " or " newpath " was too long."
+.IR target " or " linkpath " was too long."
.TP
.B ENOENT
A directory component in
-.I newpath
+.I linkpath
does not exist or is a dangling symbolic link, or
-.I oldpath
+.I target
is the empty string.
.TP
.B ENOMEM
.TP
.B ENOTDIR
A component used as a directory in
-.I newpath
+.I linkpath
is not, in fact, a directory.
.TP
.B EPERM
-The file system containing
-.I newpath
+The filesystem containing
+.I linkpath
does not support the creation of symbolic links.
.TP
.B EROFS
-.I newpath
-is on a read-only file system.
+.I linkpath
+is on a read-only filesystem.
+.PP
+The following additional errors can occur for
+.BR symlinkat ():
+.TP
+.B EBADF
+.I newdirfd
+is not a valid file descriptor.
+.TP
+.B ENOENT
+.I linkpath
+is a relative pathname and
+.IR newdirfd
+refers to a directory that has been deleted.
+.TP
+.B ENOTDIR
+.I linkpath
+is relative and
+.I newdirfd
+is a file descriptor referring to a file other than a directory.
+.SH VERSIONS
+.BR symlinkat ()
+was added to Linux in kernel 2.6.16;
+library support was added to glibc in version 2.4.
.SH CONFORMING TO
-SVr4, 4.3BSD, POSIX.1-2001.
+.BR symlink ():
+SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
.\" SVr4 documents additional error codes EDQUOT and ENOSYS.
.\" See
.\" .BR open (2)
.\" re multiple files with the same name, and NFS.
+
+.BR symlinkat ():
+POSIX.1-2008.
.SH NOTES
No checking of
-.I oldpath
+.I target
is done.
-Deleting the name referred to by a symlink will actually delete the
+Deleting the name referred to by a symbolic link will actually delete the
file (unless it also has other hard links).
If this behavior is not desired, use
.BR link (2).
+.SS Glibc notes
+On older kernels where
+.BR symlinkat ()
+is unavailable, the glibc wrapper function falls back to the use of
+.BR symlink (2).
+When
+.I linkpath
+is a relative pathname,
+glibc constructs a pathname based on the symbolic link in
+.IR /proc/self/fd
+that corresponds to the
+.IR newdirfd
+argument.
.SH SEE ALSO
.BR ln (1),
.BR lchown (2),
.BR open (2),
.BR readlink (2),
.BR rename (2),
-.BR symlinkat (2),
.BR unlink (2),
.BR path_resolution (7),
.BR symlink (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
