symlink man page on Gentoo

Man page or keyword search:  
man Server   6889 pages
apropos Keyword Search (all sections)
Output format
Gentoo logo
[printable version]

SYMLINK(3P)		   POSIX Programmer's Manual		   SYMLINK(3P)

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.

NAME
       symlink, symlinkat — make a symbolic link relative  to  directory  file
       descriptor

SYNOPSIS
       #include <unistd.h>

       int symlink(const char *path1, const char *path2);
       int symlinkat(const char *path1, int fd, const char *path2);

DESCRIPTION
       The  symlink()  function shall create a symbolic link called path2 that
       contains the string pointed to by path1 (path2 is the name of the  sym‐
       bolic  link  created,  path1  is	 the  string contained in the symbolic
       link).

       The string pointed to by path1 shall be treated	only  as  a  character
       string and shall not be validated as a pathname.

       If  the	symlink()  function fails for any reason other than [EIO], any
       file named by path2 shall be unaffected.

       If path2 names a symbolic link, symlink() shall fail and set  errno  to
       [EEXIST].

       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. Implemen‐
       tations 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.

       The  values  of	the  file  mode bits for the created symbolic link are
       unspecified. All interfaces specified by POSIX.1‐2008 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 st_mode field of  the  stat
       structure is unspecified.

       Upon  successful	 completion,  symlink() shall mark for update the last
       data access, last data modification, and last file status change	 time‐
       stamps  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.

       The  symlinkat() function shall be equivalent to the symlink() function
       except in the case where path2 specifies a relative path. In this  case
       the  symbolic link is created relative to the directory associated with
       the file descriptor fd instead of the current working directory. If the
       file  descriptor	 was opened without O_SEARCH, the function shall check
       whether directory searches are permitted using the current  permissions
       of the directory underlying the file descriptor. If the file descriptor
       was opened with O_SEARCH, the function shall not perform the check.

       If symlinkat() is passed the special value AT_FDCWD in the  fd  parame‐
       ter, the current working directory shall be used and the behavior shall
       be identical to a call to symlink().

RETURN VALUE
       Upon successful completion, these functions shall return 0.  Otherwise,
       these functions shall return −1 and set errno to indicate the error.

ERRORS
       These functions shall fail if:

       EACCES Write  permission	 is denied in the directory where the symbolic
	      link is being created, or search permission is denied for a com‐
	      ponent of the path prefix of path2.

       EEXIST The path2 argument names an existing file.

       EIO    An  I/O  error  occurs while reading from or writing to the file
	      system.

       ELOOP  A loop exists in symbolic links encountered during resolution of
	      the path2 argument.

       ENAMETOOLONG
	      The length of a component of the pathname specified by the path2
	      argument is longer than {NAME_MAX} or the length	of  the	 path1
	      argument is longer than {SYMLINK_MAX}.

       ENOENT A	 component of the path prefix of path2 does not name an exist‐
	      ing file or path2 is an empty string.

       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.

       ENOTDIR
	      A	 component  of the path prefix of path2 names an existing file
	      that is neither a directory nor a symbolic link to a directory.

       EROFS  The new symbolic link would reside on a read-only file system.

       The symlinkat() function shall fail if:

       EACCES fd was not opened with  O_SEARCH	and  the  permissions  of  the
	      directory underlying fd do not permit directory searches.

       EBADF  The  path2 argument does not specify an absolute path and the fd
	      argument is neither AT_FDCWD nor a valid	file  descriptor  open
	      for reading or searching.

       ENOTDIR
	      The  path2  argument  is	not  an absolute path and fd is a file
	      descriptor associated with a non-directory file.

       These functions may fail if:

       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered	during
	      resolution of the path2 argument.

       ENAMETOOLONG
	      The  length of the path2 argument exceeds {PATH_MAX} or pathname
	      resolution of a symbolic link in the path2 argument produced  an
	      intermediate result with a length that exceeds {PATH_MAX}.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       Like  a hard link, a symbolic link allows a file to have multiple logi‐
       cal 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 path1	 argu‐
       ment need not exist when the link is created. A symbolic link can cross
       file system boundaries.

       Normal permission checks are made on each  component  of	 the  symbolic
       link pathname during its resolution.

RATIONALE
       The  purpose of the symlinkat() 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 symlink(), resulting in unspecified behavior.  By
       opening	a  file descriptor for the target directory and using the sym‐
       linkat() function it can be guaranteed that the created	symbolic  link
       is located relative to the desired directory.

FUTURE DIRECTIONS
       None.

SEE ALSO
       fdopendir(), fstatat(), lchown(), link(), open(), readlink(), rename(),
       unlink()

       The Base Definitions volume of POSIX.1‐2008, <unistd.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal and Electronics Engineers,  Inc  and	 The  Open  Group.   (This  is
       POSIX.1-2008  with  the	2013  Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013			   SYMLINK(3P)
[top]

List of man pages available for Gentoo

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net