dep/ACE_wrappers/ace/Dirent.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Dirent.h
   6  *
   7  *  $Id: Dirent.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  Define a portable C++ interface to ACE_OS_Dirent directory-entry
  10  *  manipulation.
  11  *
  12  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  13  */
  14 //=============================================================================
  15
  16 #ifndef ACE_DIRENT_H
  17 #define ACE_DIRENT_H
  18 #include /**/ "ace/pre.h"
  19
  20 #include /**/ "ace/ACE_export.h"
  21
  22 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  23 # pragma once
  24 #endif /* ACE_LACKS_PRAGMA_ONCE */
  25
  26 #include "ace/OS_NS_dirent.h"
  27
  28 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  29
  30 /**
  31  * @class ACE_Dirent
  32  *
  33  * @brief Define a portable C++ directory-entry iterator based on the POSIX API.
  34  */
  35 class ACE_Export ACE_Dirent
  36 {
  37 public:
  38   // = Initialization and termination methods.
  39   /// Default constructor.
  40   ACE_Dirent (void);
  41
  42   /// Constructor calls <opendir>
  43   explicit ACE_Dirent (const ACE_TCHAR *dirname);
  44
  45   /// Opens the directory named by filename and associates a directory
  46   /// stream with it.
  47   int open (const ACE_TCHAR *filename);
  48
  49   /// Destructor calls <closedir>.
  50   ~ACE_Dirent (void);
  51
  52   /// Closes the directory stream and frees the <ACE_DIR> structure.
  53   void close (void);
  54
  55   // = Iterator methods.
  56   /**
  57    * Returns a pointer to a structure representing the directory entry
  58    * at the current position in the directory stream to which dirp
  59    * refers, and positions the directory stream at the next entry,
  60    * except on read-only filesystems.  It returns a NULL pointer upon
  61    * reaching the end of the directory stream, or upon detecting an
  62    * invalid location in the directory.  <readdir> shall not return
  63    * directory entries containing empty names.  It is unspecified
  64    * whether entries are returned for dot or dot-dot.  The pointer
  65    * returned by <readdir> points to data that may be overwritten by
  66    * another call to <readdir> on the same directory stream.  This
  67    * data shall not be overwritten by another call to <readdir> on a
  68    * different directory stream.  <readdir> may buffer several
  69    * directory entries per actual read operation; <readdir> marks for
  70    * update the st_atime field of the directory each time the
  71    * directory is actually read.
  72    */
  73   ACE_DIRENT *read (void);
  74
  75   /**
  76    * Has the equivalent functionality as <readdir> except that an
  77    * @a entry and @a result buffer must be supplied by the caller to
  78    * store the result.
  79    */
  80   int read (struct ACE_DIRENT *entry,
  81             struct ACE_DIRENT **result);
  82
  83   // = Manipulators.
  84   /// Returns the current location associated with the directory
  85   /// stream.
  86   long tell (void);
  87
  88   /**
  89    * Sets the position of the next <readdir> operation on the
  90    * directory stream.  The new position reverts to the position
  91    * associated with the directory stream at the time the <telldir>
  92    * operation that provides loc was performed.  Values returned by
  93    * <telldir> are good only for the lifetime of the <ACE_DIR> pointer from
  94    * which they are derived.  If the directory is closed and then
  95    * reopened, the <telldir> value may be invalidated due to
  96    * undetected directory compaction.  It is safe to use a previous
  97    * <telldir> value immediately after a call to <opendir> and before
  98    * any calls to readdir.
  99    */
 100   void seek (long loc);
 101
 102   /**
 103    * Resets the position of the directory stream to the beginning of
 104    * the directory.  It also causes the directory stream to refer to
 105    * the current state of the corresponding directory, as a call to
 106    * <opendir> would.
 107    */
 108   void rewind (void);
 109
 110 private:
 111   /// Pointer to the directory stream.
 112   ACE_DIR *dirp_;
 113 };
 114
 115 ACE_END_VERSIONED_NAMESPACE_DECL
 116
 117 #if defined (__ACE_INLINE__)
 118 #include "ace/Dirent.inl"
 119 #endif /* __ACE_INLINE__ */
 120
 121 #include /**/ "ace/post.h"
 122 #endif /* ACE_DIRENT_H */