usr/src/man/man2/getdents.2

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GETDENTS 2 "Jul 17, 2001"
   7 .SH NAME
   8 getdents \- read directory entries and put in a file system independent format
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <dirent.h>
  13
  14 \fBint\fR \fBgetdents\fR(\fBint\fR \fIfildes\fR, \fBstruct dirent *\fR\fIbuf\fR, \fBsize_t\fR \fInbyte\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The \fBgetdents()\fR function attempts to read \fInbyte\fR bytes from the
  21 directory associated with the file descriptor \fIfildes\fR and to format them
  22 as file system independent directory entries in the buffer pointed to by
  23 \fIbuf\fR. Since the file system independent directory entries are of variable
  24 lengths, in most cases the actual number of bytes returned will be less than
  25 \fInbyte\fR. The file system independent directory entry is specified by the
  26 \fBdirent\fR structure.  See \fBdirent.h\fR(3HEAD).
  27 .sp
  28 .LP
  29 On devices capable of seeking, \fBgetdents()\fR starts at a position in the
  30 file given by the file pointer associated with \fIfildes\fR. Upon return from
  31 \fBgetdents()\fR, the file pointer is incremented to point to the next
  32 directory entry.
  33 .SH RETURN VALUES
  34 .sp
  35 .LP
  36 Upon successful completion, a non-negative integer is returned indicating the
  37 number of bytes actually read. A return value of \fB0\fR indicates the end of
  38 the directory has been reached. Otherwise, \fB\(mi1\fR is returned and
  39 \fBerrno\fR is set to indicate the error.
  40 .SH ERRORS
  41 .sp
  42 .LP
  43 The \fBgetdents()\fR function will fail if:
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBEBADF\fR\fR
  48 .ad
  49 .RS 13n
  50 The \fIfildes\fR argument is not a valid file descriptor open for reading.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBEFAULT\fR\fR
  57 .ad
  58 .RS 13n
  59 The \fIbuf\fR argument points to an illegal address.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBEINVAL\fR\fR
  66 .ad
  67 .RS 13n
  68 The \fInbyte\fR argument is not large enough for one directory entry.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBEIO\fR\fR
  75 .ad
  76 .RS 13n
  77 An I/O error occurred while accessing the file system.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBENOENT\fR\fR
  84 .ad
  85 .RS 13n
  86 The current file pointer for the directory is not located at a valid entry.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBENOLINK\fR\fR
  93 .ad
  94 .RS 13n
  95 The \fIfildes\fR argument points to a remote machine and the link to that
  96 machine is no longer active.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBENOTDIR\fR\fR
 103 .ad
 104 .RS 13n
 105 The \fIfildes\fR argument is not a directory.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBEOVERFLOW\fR\fR
 112 .ad
 113 .RS 13n
 114 The value of the \fBdirent\fR structure member \fBd_ino\fR or \fBd_off\fR
 115 cannot be represented in an \fBino_t\fR or  \fBoff_t\fR.
 116 .RE
 117
 118 .SH USAGE
 119 .sp
 120 .LP
 121 The \fBgetdents()\fR function was developed to implement the \fBreaddir\fR(3C)
 122 function and should not be used for other purposes.
 123 .sp
 124 .LP
 125 The \fBgetdents()\fR function has a transitional interface for 64-bit file
 126 offsets.  See \fBlf64\fR(5).
 127 .SH SEE ALSO
 128 .sp
 129 .LP
 130 \fBreaddir\fR(3C), \fBdirent.h\fR(3HEAD), \fBlf64\fR(5)