ACE/ace/Dirent.h

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