diff options
Diffstat (limited to 'upstream/archlinux/man3p/symlink.3p')
| -rw-r--r-- | upstream/archlinux/man3p/symlink.3p | 287 |
1 files changed, 287 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/symlink.3p b/upstream/archlinux/man3p/symlink.3p new file mode 100644 index 00000000..701baae2 --- /dev/null +++ b/upstream/archlinux/man3p/symlink.3p @@ -0,0 +1,287 @@ +'\" et +.TH SYMLINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +symlink, symlinkat +\(em make a symbolic link +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +int symlink(const char *\fIpath1\fP, const char *\fIpath2\fP); +.P +#include <fcntl.h> +.P +int symlinkat(const char *\fIpath1\fP, int \fIfd\fP, const char *\fIpath2\fP); +.fi +.SH DESCRIPTION +The +\fIsymlink\fR() +function shall create a symbolic link called +.IR path2 +that contains the string pointed to by +.IR path1 +(\c +.IR path2 +is the name of the symbolic link created, +.IR path1 +is the string contained in the symbolic link). +.P +The string pointed to by +.IR path1 +shall be treated only as a string and shall not be validated +as a pathname. +.P +If the +\fIsymlink\fR() +function fails for any reason other than +.BR [EIO] , +any file named by +.IR path2 +shall be unaffected. +.P +If +.IR path2 +names a symbolic link, +\fIsymlink\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +The symbolic link's user ID shall be set to the process' effective +user ID. The symbolic link's group ID shall be set to the group +ID of the parent directory or to the effective group ID of the +process. Implementations shall provide a way to initialize the symbolic +link's group ID to the group ID of the parent directory. Implementations +may, but need not, provide an implementation-defined way to initialize the +symbolic link's group ID to the effective group ID of the calling process. +.P +The values of the file mode bits for the created symbolic link are +unspecified. All interfaces specified by POSIX.1\(hy2008 shall behave as if the +contents of symbolic links can always be read, except that the value of +the file mode bits returned in the +.IR st_mode +field of the +.BR stat +structure is unspecified. +.P +Upon successful completion, +\fIsymlink\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the symbolic link. Also, +the last data modification and last file status change timestamps of +the directory that contains the new entry shall be marked for update. +.P +The +\fIsymlinkat\fR() +function shall be equivalent to the +\fIsymlink\fR() +function except in the case where +.IR path2 +specifies a relative path. In this case the symbolic link is created +relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +If +\fIsymlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIsymlink\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +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 +.IR path2 . +.TP +.BR EEXIST +The +.IR path2 +argument names an existing file. +.TP +.BR EIO +An I/O error occurs while reading from or writing to the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of the pathname specified by the +.IR path2 +argument is longer than +{NAME_MAX} +or the length of the +.IR path1 +argument is longer than +{SYMLINK_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path2 +does not name an existing file or +.IR path2 +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path2 +argument contains at least one non-\c +<slash> +character and ends with one or more trailing +<slash> +characters. If +.IR path2 +without the trailing +<slash> +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +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, or the new symbolic link cannot be created +because no space is left on the file system which shall contain the +link, or the file system is out of file-allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix of +.IR path2 +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EROFS +The new symbolic link would reside on a read-only file system. +.P +The +\fIsymlinkat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path2 +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path2 +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR path2 +argument exceeds +{PATH_MAX} +or pathname resolution of a symbolic link in the +.IR path2 +argument produced an intermediate result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Like a hard link, a symbolic link allows a file to have multiple +logical names. The presence of a hard link guarantees the existence of +a file, even after the original name has been removed. A symbolic link +provides no such assurance; in fact, the file named by the +.IR path1 +argument need not exist when the link is created. A symbolic link can +cross file system boundaries. +.P +Normal permission checks are made on each component of the symbolic +link pathname during its resolution. +.SH RATIONALE +The purpose of the +\fIsymlinkat\fR() +function is to create symbolic links in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIsymlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIsymlinkat\fR() +function it can be guaranteed that the created symbolic link is located +relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIreadlink\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<fcntl.h>\fP", +.IR "\fB<unistd.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |