original/man3/scandirat.3

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (c) 2012, Mark R. Bannister <cambridge@users.sourceforge.net>
   4 .\"        based on text in mkfifoat.3 Copyright (c) 2006, Michael Kerrisk
   5 .\"
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\"
  11 .\" The GNU General Public License's references to "object code"
  12 .\" and "executables" are to be interpreted as the output of any
  13 .\" document formatting or typesetting system, including
  14 .\" intermediate and printed output.
  15 .\"
  16 .\" This manual is distributed in the hope that it will be useful,
  17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 .\" GNU General Public License for more details.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public
  22 .\" License along with this manual; if not, write to the Free
  23 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  24 .\" USA.
  25 .\"
  26 .TH SCANDIRAT 3 2012-03-17 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 scandirat \- scan a directory relative to a directory file descriptor
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  32
  33 .BR "#include <fcntl.h>" "          /* Definition of AT_* constants */"
  34 .B #include <dirent.h>
  35 .sp
  36 .fi
  37 .BI "int scandirat(int " dirfd ", const char *" dirp ","
  38 .BI "struct dirent ***" namelist ,
  39 .nf
  40 .RS
  41 .BI "int (*" filter ")(const struct dirent *),"
  42 .BI "int (*" compar ")(const struct dirent **, const struct dirent **));"
  43 .RE
  44 .fi
  45 .SH DESCRIPTION
  46 The
  47 .BR scandirat ()
  48 system call operates in exactly the same way as
  49 .BR scandir (3),
  50 except for the differences described in this manual page.
  51
  52 If the pathname given in
  53 .I dirp
  54 is relative, then it is interpreted relative to the directory
  55 referred to by the file descriptor
  56 .I dirfd
  57 (rather than relative to the current working directory of
  58 the calling process, as is done by
  59 .BR scandir (3)
  60 for a relative pathname).
  61
  62 If
  63 .I dirp
  64 is relative and
  65 .I dirfd
  66 is the special value
  67 .BR AT_FDCWD ,
  68 then
  69 .I dirp
  70 is interpreted relative to the current working
  71 directory of the calling process (like
  72 .BR scandir (3)).
  73
  74 If
  75 .I dirp
  76 is absolute, then
  77 .I dirfd
  78 is ignored.
  79 .SH "RETURN VALUE"
  80 On success,
  81 .BR scandirat ()
  82 returns the number of directory entries selected.
  83 On error, \-1 is returned and
  84 .I errno
  85 is set to indicate the error.
  86 .SH ERRORS
  87 The same errors that occur for
  88 .BR scandir (3)
  89 can also occur for
  90 .BR scandirat ().
  91 The following additional errors can occur for
  92 .BR scandirat ():
  93 .TP
  94 .B EBADF
  95 .I dirfd
  96 is not a valid file descriptor.
  97 .TP
  98 .B ENOTDIR
  99 .I dirp
 100 is a relative path and
 101 .I dirfd
 102 is a file descriptor referring to a file other than a directory.
 103 .SH VERSIONS
 104 .BR scandirat ()
 105 was added to glibc in version 2.15.
 106 .SH "CONFORMING TO"
 107 This function is a GNU extension.
 108 .SH NOTES
 109 See
 110 .BR openat (2)
 111 for an explanation of the need for
 112 .BR scandirat ().
 113 .SH "SEE ALSO"
 114 .BR openat (2),
 115 .BR scandir (3),
 116 .BR path_resolution (7)