man2/unlinkat.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" This manpage is Copyright (C) 2006, Michael Kerrisk
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .\"
  26 .TH UNLINKAT 2 2006-04-10 "Linux 2.6.16" "Linux Programmer's Manual"
  27 .SH NAME
  28 unlinkat \- remove a directory entry relative to a directory file descriptor
  29 .SH SYNOPSIS
  30 .nf
  31 .B #define _ATFILE_SOURCE
  32 .B #include <fcntl.h>
  33 .sp
  34 .BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags );
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR unlinkat ()
  39 system call operates in exactly the same way as either
  40 .BR unlink (2)
  41 or
  42 .BR rmdir (2)
  43 (depending on whether or not
  44 .I flags
  45 includes the
  46 .B AT_REMOVEDIR
  47 flag)
  48 except for the differences described in this manual page.
  49
  50 If the pathname given in
  51 .I pathname
  52 is relative, then it is interpreted relative to the directory
  53 referred to by the file descriptor
  54 .IR dirfd
  55 (rather than relative to the current working directory of
  56 the calling process, as is done by
  57 .BR unlink (2)
  58 and
  59 .BR rmdir (2)
  60 for a relative pathname).
  61
  62 If the pathname given in
  63 .I pathname
  64 is relative and
  65 .I dirfd
  66 is the special value
  67 .BR AT_FDCWD ,
  68 then
  69 .I pathname
  70 is interpreted relative to the current working
  71 directory of the calling process (like
  72 .BR unlink (2)
  73 and
  74 .BR rmdir (2)).
  75
  76 If the pathname given in
  77 .IR pathname
  78 is absolute, then
  79 .I dirfd
  80 is ignored.
  81
  82 .I flags
  83 is a bit mask that can either be specified as 0, or by ORing
  84 together flag values that control the operation of
  85 .BR unlinkat ().
  86 Currently only one such flags is defined:
  87 .TP
  88 .B AT_REMOVEDIR
  89 By default,
  90 .BR unlinkat ()
  91 performs the equivalent of
  92 .BR unlink (2)
  93 on
  94 .IR pathname .
  95 If the
  96 .B AT_REMOVEDIR
  97 flag is specified, then
  98 performs the equivalent of
  99 .BR rmdir (2)
 100 on
 101 .IR pathname .
 102 .SH "RETURN VALUE"
 103 On success,
 104 .BR unlinkat ()
 105 returns 0.
 106 On error, \-1 is returned and
 107 .I errno
 108 is set to indicate the error.
 109 .SH ERRORS
 110 The same errors that occur for
 111 .BR unlink (2)
 112 and
 113 .BR rmdir (2)
 114 can also occur for
 115 .BR unlinkat ().
 116 The following additional errors can occur for
 117 .BR unlinkat ():
 118 .TP
 119 .B EBADF
 120 .I dirfd
 121 is not a valid file descriptor.
 122 .TP
 123 .B EINVAL
 124 An invalid flag value was specified in
 125 .IR flags .
 126 .TP
 127 .B ENOTDIR
 128 .I pathname
 129 is relative and
 130 .I dirfd
 131 is a file descriptor referring to a file other than a directory.
 132 .SH NOTES
 133 See
 134 .BR openat (2)
 135 for an explanation of the need for
 136 .BR unlinkat ().
 137 .SH "CONFORMING TO"
 138 This system call is non-standard but is proposed
 139 for inclusion in a future revision of POSIX.1.
 140 A similar system call exists on Solaris.
 141 .SH VERSIONS
 142 .BR unlinkat ()
 143 was added to Linux in kernel 2.6.16.
 144 .SH "SEE ALSO"
 145 .BR openat (2),
 146 .BR path_resolution (2),
 147 .BR rmdir (2),
 148 .BR unlink (2)