doc/html/ref/fileio-directories.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Directories</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="File System Support Infrastructure"
  23 HREF="fileio.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="File Table"
  26 HREF="fileio-file-table.html"><LINK
  27 REL="NEXT"
  28 TITLE="Synchronization"
  29 HREF="fileio-synchronization.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="fileio-file-table.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="fileio-synchronization.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="FILEIO-DIRECTORIES">Chapter 23. Directories</H1
  85 ><P
  86 >Filesystem operations all take a directory pointer as one of their
  87 arguments.  A directory pointer is an opaque handle managed by the
  88 filesystem. It should encapsulate a reference to a specific directory
  89 within the filesystem. For example, it may be a pointer to the data
  90 structure that represents that directory (such as an inode), or a
  91 pointer to a pathname for the directory.</P
  92 ><P
  93 >The <TT
  94 CLASS="FUNCTION"
  95 >chdir()</TT
  96 > filesystem function pointer has two
  97 modes of use. When passed a pointer in the
  98 <TT
  99 CLASS="PARAMETER"
 100 ><I
 101 >dir_out</I
 102 ></TT
 103 > argument, it should locate the named
 104 directory and place a directory pointer there. If the
 105 <TT
 106 CLASS="PARAMETER"
 107 ><I
 108 >dir_out</I
 109 ></TT
 110 > argument is NULL then the
 111 <TT
 112 CLASS="PARAMETER"
 113 ><I
 114 >dir</I
 115 ></TT
 116 > argument is a previously generated
 117 directory pointer that can now be disposed of. When the infrastructure
 118 is implementing the <TT
 119 CLASS="FUNCTION"
 120 >chdir()</TT
 121 > function it makes two
 122 calls to filesystem <TT
 123 CLASS="FUNCTION"
 124 >chdir()</TT
 125 > functions. The first
 126 is to get a directory pointer for the new current directory. If this
 127 succeeds the second is to dispose of the old current directory
 128 pointer.</P
 129 ><P
 130 >The <TT
 131 CLASS="FUNCTION"
 132 >opendir()</TT
 133 > function is used to open a
 134 directory for reading. This results in an open file object that can be
 135 read to return a sequence of <SPAN
 136 CLASS="STRUCTNAME"
 137 >struct dirent</SPAN
 138 >
 139 objects. The only operations that are allowed on this file are
 140 <TT
 141 CLASS="FUNCTION"
 142 >read</TT
 143 >, <TT
 144 CLASS="FUNCTION"
 145 >lseek</TT
 146 > and
 147 <TT
 148 CLASS="FUNCTION"
 149 >close</TT
 150 >. Each read operation on this file should
 151 return a single <SPAN
 152 CLASS="STRUCTNAME"
 153 >struct dirent</SPAN
 154 > object. When
 155 the end of the directory is reached, zero should be returned. The only
 156 seek operation allowed is a rewind to the start of the directory, by
 157 supplying an offset of zero and a <TT
 158 CLASS="PARAMETER"
 159 ><I
 160 >whence</I
 161 ></TT
 162 >
 163 specifier of <TT
 164 CLASS="LITERAL"
 165 >SEEK_SET</TT
 166 >.</P
 167 ><P
 168 >Most of these considerations are invisible to clients of a filesystem
 169 since they will access directories via the POSIX
 170 <TT
 171 CLASS="FUNCTION"
 172 >opendir()</TT
 173 >, <TT
 174 CLASS="FUNCTION"
 175 >readdir()</TT
 176 > and
 177 <TT
 178 CLASS="FUNCTION"
 179 >closedir()</TT
 180 > functions.</P
 181 ><P
 182 >Support for the <TT
 183 CLASS="FUNCTION"
 184 >getcwd()</TT
 185 > function is provided by
 186 three mechanisms.  The first is to use the
 187 <TT
 188 CLASS="LITERAL"
 189 >FS_INFO_GETCWD</TT
 190 > getinfo key on the filesystem to use
 191 any internal support that it has for this. If that fails it falls back
 192 on one of the two other mechanisms. If
 193 <TT
 194 CLASS="LITERAL"
 195 >CYGPKG_IO_FILEIO_TRACK_CWD</TT
 196 > is set then the current
 197 directory is tracked textually in <TT
 198 CLASS="FUNCTION"
 199 >chdir()</TT
 200 > and the result of that is
 201 reported in getcwd(). Otherwise an attempt is made to traverse the
 202 directory tree to its root using &quot;..&quot; entries.</P
 203 ><P
 204 >This last option is complicated and expensive, and relies on the
 205 filesystem supporting &quot;.&quot; and &quot;..&quot;  entries. This is not always the
 206 case, particularly if the filesystem has been ported from a
 207 non-UNIX-compatible source. Tracking the pathname textually will
 208 usually work, but might not produce optimum results when symbolic
 209 links are being used.</P
 210 ></DIV
 211 ><DIV
 212 CLASS="NAVFOOTER"
 213 ><HR
 214 ALIGN="LEFT"
 215 WIDTH="100%"><TABLE
 216 SUMMARY="Footer navigation table"
 217 WIDTH="100%"
 218 BORDER="0"
 219 CELLPADDING="0"
 220 CELLSPACING="0"
 221 ><TR
 222 ><TD
 223 WIDTH="33%"
 224 ALIGN="left"
 225 VALIGN="top"
 226 ><A
 227 HREF="fileio-file-table.html"
 228 ACCESSKEY="P"
 229 >Prev</A
 230 ></TD
 231 ><TD
 232 WIDTH="34%"
 233 ALIGN="center"
 234 VALIGN="top"
 235 ><A
 236 HREF="ecos-ref.html"
 237 ACCESSKEY="H"
 238 >Home</A
 239 ></TD
 240 ><TD
 241 WIDTH="33%"
 242 ALIGN="right"
 243 VALIGN="top"
 244 ><A
 245 HREF="fileio-synchronization.html"
 246 ACCESSKEY="N"
 247 >Next</A
 248 ></TD
 249 ></TR
 250 ><TR
 251 ><TD
 252 WIDTH="33%"
 253 ALIGN="left"
 254 VALIGN="top"
 255 >File Table</TD
 256 ><TD
 257 WIDTH="34%"
 258 ALIGN="center"
 259 VALIGN="top"
 260 ><A
 261 HREF="fileio.html"
 262 ACCESSKEY="U"
 263 >Up</A
 264 ></TD
 265 ><TD
 266 WIDTH="33%"
 267 ALIGN="right"
 268 VALIGN="top"
 269 >Synchronization</TD
 270 ></TR
 271 ></TABLE
 272 ></DIV
 273 ></BODY
 274 ></HTML
 275 >