'\" te .\" Copyright 1989 AT&T .\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. .\" Portions Copyright (c) 2007, 2015, Oracle and/or its affiliates. All rights reserved. .\" Oracle gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. This notice shall appear on any product containing this material. .TH symlink 2 "12 Jan 2015" "SunOS 5.11" "System Calls" .SH NAME symlink, symlinkat \- make a symbolic link to a file .SH SYNOPSIS .LP .nf #include \fBint\fR \fBsymlink\fR(\fBconst char *\fR\fIpath1\fR, \fBconst char *\fR\fIpath2\fR); .fi .LP .nf \fBint\fR \fBsymlinkat\fR(\fBconst char *\fR\fIpath1\fR,int \fIfd\fR, \fBconst char *\fR\fIpath2\fR); .fi .SH DESCRIPTION .sp .LP The \fBsymlink()\fR function creates a symbolic link \fIpath2\fR to the file \fIpath1\fR. Either name may be an arbitrary pathname, the files need not be on the same file system, and \fIpath1\fR may be nonexistent. .sp .LP The file to which the symbolic link points is used when an \fBopen\fR(2) operation is performed on the link. A \fBstat()\fR operation performed on a symbolic link returns the linked-to file, while an \fBlstat()\fR operation returns information about the link itself. See \fBstat\fR(2). Unexpected results may occur when a symbolic link is made to a directory. To avoid confusion in applications, the \fBreadlink\fR(2) call can be used to read the contents of a symbolic link. .sp .LP The \fBsymlinkat()\fR function is equivalent to the \fBsymlink()\fR function except in the case where \fIpath2\fR specifies a relative path. In this case the symbolic link is created relative to the directory associated with the file descriptor \fIfd\fR instead of the current working directory. If the file descriptor was opened without \fBO_SEARCH\fR, the function checks whether directory searches are permitted using the current permissions of the directory underlying the file descriptor. If the file descriptor was opened with \fBO_SEARCH\fR, the function does not perform the check. .sp .LP If \fBsymlinkat()\fR is passed the special value \fBAT_FDCWD\fR in the \fIfd\fR parameter, the current working directory is used and the behavior is identical to a call to \fBsymlink()\fR. .SH RETURN VALUES .sp .LP Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is returned, \fBerrno\fR is set to indicate the error, and the symbolic link is not made. .SH ERRORS .sp .LP The \fBsymlink()\fR and \fBsymlinkat()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 16n .rt Write permission is denied in the directory where the symbolic link is being created, or search permission is denied for a component of the path prefix of \fIpath2\fR. .RE .sp .ne 2 .mk .na \fB\fBEDQUOT\fR\fR .ad .RS 16n .rt The directory where the entry for the new symbolic link is being placed cannot be extended because the user's quota of disk blocks on that file system has been exhausted; the new symbolic link cannot be created because the user's quota of disk blocks on that file system has been exhausted; or the user's quota of inodes on the file system where the file is being created has been exhausted. .RE .sp .ne 2 .mk .na \fB\fBEEXIST\fR\fR .ad .RS 16n .rt The file referred to by \fIpath2\fR already exists. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 16n .rt The \fIpath1\fR or \fIpath2\fR argument points to an illegal address. .RE .sp .ne 2 .mk .na \fB\fBEILSEQ\fR\fR .ad .RS 16n .rt The path argument includes non-UTF8 characters and the file system accepts only file names where all characters are part of the UTF-8 character codeset. .RE .sp .ne 2 .mk .na \fB\fBEIO\fR\fR .ad .RS 16n .rt An I/O error occurs while reading from or writing to the file system. .RE .sp .ne 2 .mk .na \fB\fBELOOP\fR\fR .ad .RS 16n .rt Too many symbolic links are encountered in translating \fIpath2\fR. .RE .sp .ne 2 .mk .na \fB\fBENAMETOOLONG\fR\fR .ad .RS 16n .rt The length of the \fIpath2\fR argument exceeds \fBPATH_MAX\fR, or the length of a \fIpath2\fR component exceeds \fBNAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in effect. .sp This error can also be returned if the length of the \fIpath1\fR argument exceeds \fBSYMLINK_MAX\fR. .RE .sp .ne 2 .mk .na \fB\fBENOENT\fR\fR .ad .RS 16n .rt A component of the path prefix of \fIpath2\fR does not exist. .RE .sp .ne 2 .mk .na \fB\fBENOSPC\fR\fR .ad .RS 16n .rt The directory in which the entry for the new symbolic link is being placed cannot be extended because no space is left on the file system containing the directory; the new symbolic link cannot be created because no space is left on the file system which will contain the link; or there are no free inodes on the file system on which the file is being created. .RE .sp .ne 2 .mk .na \fB\fBENOSYS\fR\fR .ad .RS 16n .rt The file system does not support symbolic links. .RE .sp .ne 2 .mk .na \fB\fBENOTDIR\fR\fR .ad .RS 16n .rt A component of the path prefix of \fIpath2\fR is not a directory. .RE .sp .ne 2 .mk .na \fB\fBEROFS\fR\fR .ad .RS 16n .rt The file \fIpath2\fR would reside on a read-only file system. .RE .sp .LP The \fBsymlinkat()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 10n .rt \fIfd\fR was not opened with \fBO_SEARCH\fR and the permissions of the directory underlying \fIfd\fR do not permit directory searches. .RE .sp .ne 2 .mk .na \fB\fBEBADF\fR\fR .ad .RS 10n .rt The \fIpath2\fR argument does not specify an absolute path and the \fIfd\fR argument is neither \fBAT_FDCWD\fR nor a valid file descriptor open for reading or searching. .RE .sp .LP The \fBsymlink()\fR and \fBsymlinkat()\fR functions may fail if: .sp .ne 2 .mk .na \fB\fBELOOP\fR\fR .ad .RS 16n .rt More than {\fBSYMLOOP_MAX\fR} symbolic links were encountered during resolution of the \fIpath2\fR argument. .RE .sp .ne 2 .mk .na \fB\fBENAMETOOLONG\fR\fR .ad .RS 16n .rt The length of the \fIpath2\fR argument exceeds {\fBPATH_MAX\fR} or pathname resolution of a symbolic link in the \fIpath2\fR argument produced an intermediate result with a length that exceeds {\fBPATH_MAX\fR}. .RE .sp .LP The \fBsymlinkat()\fR function may fail if: .sp .ne 2 .mk .na \fB\fBENOTDIR\fR\fR .ad .RS 11n .rt The \fIpath2\fR argument is not an absolute path and \fIfd\fR is neither \fBAT_FDCWD\fR nor a file descriptor associated with a directory .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ StandardSee \fBstandards\fR(5). .TE .SH SEE ALSO .sp .LP \fBcp\fR(1), \fBlink\fR(2), \fBopen\fR(2), \fBreadlink\fR(2), \fBstat\fR(2), \fBunlink\fR(2), \fBattributes\fR(5)