lib/libc/sys/symlink.2

   1 .\"     $NetBSD: symlink.2,v 1.26 2013/07/29 11:40:04 njoly Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)symlink.2   8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd July 29, 2013
  33 .Dt SYMLINK 2
  34 .Os
  35 .Sh NAME
  36 .Nm symlink ,
  37 .Nm symlinkat
  38 .Nd make symbolic link to a file
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Ft int
  44 .Fn symlink "const char *name1" "const char *name2"
  45 .Ft int
  46 .Fn symlinkat "const char *name1" "int fd" "const char *name2"
  47 .Sh DESCRIPTION
  48 A symbolic link
  49 .Fa name2
  50 is created to
  51 .Fa name1
  52 .Pf ( Fa name2
  53 is the name of the
  54 file created,
  55 .Fa name1
  56 is the string
  57 used in creating the symbolic link).
  58 Either name may be an arbitrary path name; the files need neither
  59 to be on the same file system nor to exist.
  60 .Pp
  61 .Fn symlinkat
  62 works the same way as
  63 .Fn symlink
  64 except if
  65 .Fa path2
  66 is relative.
  67 In that case, it is looked up from a directory whose file
  68 descriptor was passed as
  69 .Fa fd .
  70 Search permission is required on this directory.
  71 .\"    (These alternatives await a decision about the semantics of O_SEARCH)
  72 .\" Search permission is required on this directory
  73 .\" except if
  74 .\" .Fa fd
  75 .\" was opened with the
  76 .\" .Dv O_SEARCH
  77 .\" flag.
  78 .\"    - or -
  79 .\" This file descriptor must have been opened with the
  80 .\" .Dv O_SEARCH
  81 .\" flag.
  82 .Fa fd
  83 can be set to
  84 .Dv AT_FDCWD
  85 in order to specify the current directory.
  86 .Sh RETURN VALUES
  87 .Rv -std symlink symlinkat
  88 .Sh ERRORS
  89 .Fn symlink
  90 and
  91 .Fn symlinkat
  92 will fail and no link will be created if:
  93 .Bl -tag -width Er
  94 .It Bq Er EACCES
  95 A component of the
  96 .Fa name2
  97 path prefix denies search permission.
  98 .It Bq Er EDQUOT
  99 The directory in which the entry for the new symbolic link
 100 is being placed cannot be extended because the
 101 user's quota of disk blocks on the file system
 102 containing the directory has been exhausted.
 103 Or, the new symbolic link cannot be created because the user's
 104 quota of disk blocks on the file system that will
 105 contain the symbolic link has been exhausted.
 106 Or, the user's quota of inodes on the file system on
 107 which the symbolic link is being created has been exhausted.
 108 .It Bq Er EEXIST
 109 .Fa name2
 110 already exists.
 111 .It Bq Er EFAULT
 112 .Fa name1
 113 or
 114 .Fa name2
 115 points outside the process's allocated address space.
 116 .It Bq Er EIO
 117 An I/O error occurred while making the directory entry for
 118 .Fa name2 ,
 119 or allocating the inode for
 120 .Fa name2 ,
 121 or writing out the link contents of
 122 .Fa name2 .
 123 Or, an I/O error occurred while making the directory entry or allocating the inode.
 124 .It Bq Er ELOOP
 125 Too many symbolic links were encountered in translating the pathname.
 126 .It Bq Er ENAMETOOLONG
 127 A component of a pathname exceeded
 128 .Brq Dv NAME_MAX
 129 characters, or an entire path name exceeded
 130 .Brq Dv PATH_MAX
 131 characters.
 132 .It Bq Er ENOENT
 133 A component of the
 134 .Fa name2
 135 path does not exist.
 136 .It Bq Er ENOSPC
 137 The directory in which the entry for the new symbolic link is being placed
 138 cannot be extended because there is no space left on the file
 139 system containing the directory.
 140 Or, the new symbolic link cannot be created because there
 141 there is no space left on the file
 142 system that will contain the symbolic link.
 143 Or, there are no free inodes on the file system on which the
 144 symbolic link is being created.
 145 .It Bq Er ENOTDIR
 146 A component of the
 147 .Fa name2
 148 prefix is not a directory.
 149 .It Bq Er EROFS
 150 The file
 151 .Fa name2
 152 would reside on a read-only file system.
 153 .El
 154 .Pp
 155 In addition,
 156 .Fn symlinkat
 157 will fail if:
 158 .Bl -tag -width Er
 159 .It Bq Er EBADF
 160 .Fa name2
 161 does not specify an absolute path and
 162 .Fa fd
 163 is neither
 164 .Dv AT_FDCWD
 165 nor a valid file descriptor open for reading or searching.
 166 .It Bq Er ENOTDIR
 167 .Fa name2
 168 is not an absolute path and
 169 .Fa fd
 170 is a file descriptor associated with a non-directory file.
 171 .El
 172 .Sh SEE ALSO
 173 .Xr ln 1 ,
 174 .Xr link 2 ,
 175 .Xr readlink 2 ,
 176 .Xr unlink 2 ,
 177 .Xr symlink 7
 178 .Sh STANDARDS
 179 The
 180 .Fn symlink
 181 function conforms to
 182 .St -p1003.1-90 .
 183 .Fn symlinkat
 184 conforms to
 185 .St -p1003.1-2008 .
 186 .Sh HISTORY
 187 The
 188 .Fn symlink
 189 function call appeared in
 190 .Bx 4.2 .