| .\" 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 |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified 1993-07-24 by Rik Faith |
| .\" Modified 1996-04-26 by Nick Duffek <nsd@bbc.com> |
| .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com> |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| symlink, symlinkat \- make a new name for a file |
| .SH SYNOPSIS |
| .nf |
| .B #include <unistd.h> |
| .PP |
| .BI "int symlink(const char *" target ", const char *" linkpath ); |
| .PP |
| .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
| .B #include <unistd.h> |
| .PP |
| .BI "int symlinkat(const char *" target ", int " newdirfd \ |
| ", const char *" linkpath ); |
| .PP |
| .fi |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR symlink (): |
| .nf |
| _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L |
| .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED |
| || /* Glibc <= 2.19: */ _BSD_SOURCE |
| .fi |
| .PP |
| .BR symlinkat (): |
| .nf |
| Since glibc 2.10: |
| _POSIX_C_SOURCE >= 200809L |
| Before glibc 2.10: |
| _ATFILE_SOURCE |
| .fi |
| .SH DESCRIPTION |
| .BR symlink () |
| creates a symbolic link named |
| .I linkpath |
| which contains the string |
| .IR target . |
| .PP |
| 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 |
| directory. |
| .PP |
| Symbolic links may contain |
| .I .. |
| path components, which (if used at the start of the link) refer to the |
| parent directories of that in which the link resides. |
| .PP |
| A symbolic link (also known as a soft link) may point to an existing |
| file or to a nonexistent one; the latter case is known as a dangling |
| link. |
| .PP |
| The permissions of a symbolic link are irrelevant; the ownership is |
| ignored when following the link, but is checked when removal or |
| renaming of the link is requested and the link is in a directory with |
| the sticky bit |
| .RB ( S_ISVTX ) |
| set. |
| .PP |
| If |
| .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. |
| .PP |
| 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). |
| .PP |
| 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 ()). |
| .PP |
| If |
| .I linkpath |
| is absolute, then |
| .I newdirfd |
| is ignored. |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| Write access to the directory containing |
| .I linkpath |
| is denied, or one of the directories in the path prefix of |
| .I linkpath |
| did not allow search permission. |
| (See also |
| .BR path_resolution (7).) |
| .TP |
| .B EDQUOT |
| 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 linkpath |
| already exists. |
| .TP |
| .B EFAULT |
| .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 linkpath . |
| .TP |
| .B ENAMETOOLONG |
| .IR target " or " linkpath " was too long." |
| .TP |
| .B ENOENT |
| A directory component in |
| .I linkpath |
| does not exist or is a dangling symbolic link, or |
| .I target |
| or |
| .I linkpath |
| is an empty string. |
| .TP |
| .B ENOMEM |
| Insufficient kernel memory was available. |
| .TP |
| .B ENOSPC |
| The device containing the file has no room for the new directory |
| entry. |
| .TP |
| .B ENOTDIR |
| A component used as a directory in |
| .I linkpath |
| is not, in fact, a directory. |
| .TP |
| .B EPERM |
| The filesystem containing |
| .I linkpath |
| does not support the creation of symbolic links. |
| .TP |
| .B EROFS |
| .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 |
| .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. |
| .PP |
| .BR symlinkat (): |
| POSIX.1-2008. |
| .SH NOTES |
| No checking of |
| .I target |
| is done. |
| .PP |
| 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 (). |
| 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 namei (1), |
| .BR lchown (2), |
| .BR link (2), |
| .BR lstat (2), |
| .BR open (2), |
| .BR readlink (2), |
| .BR rename (2), |
| .BR unlink (2), |
| .BR path_resolution (7), |
| .BR symlink (7) |