'\" te .\" Portions Copyright (c) 2007, 2014, Oracle and/or its affiliates. All rights reserved. .\" Copyright 1989 AT&T .TH link 2 "21 Mar 2014" "SunOS 5.11" "System Calls" .SH NAME link, linkat \- link to a file .SH SYNOPSIS .LP .nf #include \fBint\fR \fBlink\fR(\fBconst char *\fR\fIpath1\fR, \fBconst char *\fR\fIpath2\fR); .fi .LP .nf int linkat(int \fIfd1\fR, const char *\fIpath1\fR, int \fIfd2\fR, const char *\fIpath2\fR, int \fIflag\fR); .fi .SH DESCRIPTION .sp .LP The \fBlink()\fR function creates a new link (directory entry) for the existing file and increments its link count by one. The \fIpath1\fR argument points to a path name naming an existing file. The \fIpath2\fR argument points to a pathname naming the new directory entry to be created. .sp .LP To create hard links, both files must be on the same file system. Both the old and the new link share equal access and rights to the underlying object. No process can make a link to a directory, file named by \fIpath1\fR must not be a directory. .sp .LP Upon successful completion, \fBlink()\fR marks for update the \fBst_ctime\fR field of the file. Also, the \fBst_ctime\fR and \fBst_mtime\fR fields of the directory that contains the new entry are marked for update. .sp .LP If \fBlink()\fR fails, no link is created and the link count of the file remains unchanged. .sp .LP The \fBlinkat()\fR function is equivalent to \fBlink()\fR except in the case where either \fIpath1\fR or \fIpath2\fR or both are relative paths. In this case a relative path \fIpath1\fR is interpreted relative to the directory associated with the file descriptor \fIfd1\fR instead of the current working directory and similarly for \fIpath2\fR and the file descriptor \fIfd2\fR. 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 Values for \fIflag\fR are constructed by a bitwise-inclusive OR of flags from the following list, defined in \fB\fR. .sp .ne 2 .mk .na \fB\fBAT_SYMLINK_FOLLOW\fR\fR .ad .RS 21n .rt If \fIpath1\fR names a symbolic link, a new link for the target of the symbolic link is created. .RE .sp .LP If \fBlinkat()\fR is passed the special value \fBAT_FDCWD\fR in the \fIfd1\fR or \fIfd2\fR parameter, the current working directory is used for the respective path argument. If both \fIfd1\fR and \fIfd2\fR have value \fBAT_FDCWD\fR, the behavior is identical to a call to \fBlink()\fR. .sp .LP If the \fBAT_SYMLINK_FOLLOW\fR flag is clear in the \fIflag\fR argument and the \fIpath1\fR argument names a symbolic link, a new link is created for the symbolic link \fIpath1\fR and not its target. .SH RETURN VALUES .sp .LP Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is returned, no link is created, and \fBerrno\fR is set to indicate the error. .SH ERRORS .sp .LP The \fBlink()\fR and \fBlinkat()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 16n .rt A component of either path prefix denies search permission, or the requested link requires writing in a directory with a mode that denies write permission. .RE .sp .ne 2 .mk .na \fB\fBEDQUOT\fR\fR .ad .RS 16n .rt The directory where the entry for the new link is being placed cannot be extended because the user's quota of disk blocks on that file system has been exhausted. .RE .sp .ne 2 .mk .na \fB\fBEEXIST\fR\fR .ad .RS 16n .rt The link named by \fIpath2\fR 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\fBEINTR\fR\fR .ad .RS 16n .rt A signal was caught during the execution of the \fBlink()\fR function. .RE .sp .ne 2 .mk .na \fB\fBELOOP\fR\fR .ad .RS 16n .rt Too many symbolic links were encountered in translating \fIpath\fR. .RE .sp .ne 2 .mk .na \fB\fBEMLINK\fR\fR .ad .RS 16n .rt The maximum number of links to a file would be exceeded. .RE .sp .ne 2 .mk .na \fB\fBENAMETOOLONG\fR\fR .ad .RS 16n .rt The length of the \fIpath1\fR or \fIpath2\fR argument exceeds \fBPATH_MAX\fR, or the length of a \fIpath1\fR or \fIpath2\fR component exceeds \fBNAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in effect. .RE .sp .ne 2 .mk .na \fB\fBENOENT\fR\fR .ad .RS 16n .rt The \fIpath1\fR or \fIpath2\fR argument is a null pathname; a component of either path prefix does not exist; or the file named by \fIpath1\fR does not exist. .RE .sp .ne 2 .mk .na \fB\fBENOLINK\fR\fR .ad .RS 16n .rt The \fIpath1\fR or \fIpath2\fR argument points to a remote machine and the link to that machine is no longer active. .RE .sp .ne 2 .mk .na \fB\fBENOSPC\fR\fR .ad .RS 16n .rt The directory that would contain the link cannot be extended. .RE .sp .ne 2 .mk .na \fB\fBENOTDIR\fR\fR .ad .RS 16n .rt A component of either path prefix is not a directory. .RE .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 16n .rt The file named by \fIpath1\fR is a directory; this implementation probibits links to directories. .sp The effective user ID does not match the owner of the file and the {\fBPRIV_FILE_LINK_ANY\fR} privilege is not asserted in the effective set of the calling process. .RE .sp .ne 2 .mk .na \fB\fBEROFS\fR\fR .ad .RS 16n .rt The requested link requires writing in a directory on a read-only file system. .sp The file named by \fIpath1\fR is read-only because of the \fBmwac\fR(5) policy. .RE .sp .ne 2 .mk .na \fB\fBEXDEV\fR\fR .ad .RS 16n .rt The link named by \fIpath2\fR and the file named by \fIpath1\fR are on different logical devices (file systems). .RE .sp .LP The \fBlinkat()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEBADF\fR\fR .ad .RS 9n .rt The \fIpath1\fR or \fIpath2\fR argument does not specify an absolute path and the \fIfd1\fR or \fIfd2\fR argument, respectively, is neither \fBAT_FDCWD\fR nor a valid file descriptor open for reading. .RE .sp .LP The \fBlink()\fR and \fBlinkat()\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 \fIpath1\fR or \fIpath2\fR argument. .RE .sp .ne 2 .mk .na \fB\fBENAMETOOLONG\fR\fR .ad .RS 16n .rt The length of a pathname exceeds {\fBPATH_MAX\fR}, or pathname resolution of a symbolic link produced an intermediate result with a length that exceeds {\fBPATH_MAX\fR}. .RE .sp .ne 2 .mk .na \fB\fBEXDEV\fR\fR .ad .RS 16n .rt The link named by \fIpath2\fR and the file named by \fIpath1\fR are on different logical devices (file systems). .RE .sp .LP The \fBlinkat()\fR function may fail if: .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 11n .rt The value of the \fIflag\fR argument is not valid. .RE .sp .ne 2 .mk .na \fB\fBENOTDIR\fR\fR .ad .RS 11n .rt The \fIpath1\fR or \fIpath2\fR argument is not an absolute path and \fIfd1\fR or \fIfd2\fR, respectively, 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 _ MT-LevelAsync-Signal-Safe _ StandardSee \fBstandards\fR(5). .TE .SH SEE ALSO .sp .LP \fBsymlink\fR(2), \fBunlink\fR(2), \fBattributes\fR(5), \fBmwac\fR(5), \fBprivileges\fR(5), \fBstandards\fR(5)