wy_dirfile.3wy

一个不错

.TH Wy_DirFile 3wy "libwy v0.31"
.SH NAME
Wy_DirFile \- handle class of system directory file
.SH SYNOPSIS
.B #include <wy_dirfile.h>
.PP
[\fBInherit\fP]
.PP
Wy_DirFile is a handle class for the system directory file

Note: Directory file may be handled by another process at the 
      same time, i.e. the contents of the directory is volatile.
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 \fBWy_DirFile\fP()
 \fBWy_DirFile\fP(const Wy_DirFile&)
 \fBWy_DirFile\fP(const char*)
 \fBWy_DirFile\fP(const WyStr&)
 \fBWy_DirFile\fP(Wy_DirFile&, Wy::ByMove_t) throw()
 virtual \fB~Wy_DirFile\fP()
 bool \fBis_default\fP(void) const throw()
 WyFileHandle \fBfh\fP(void) const throw()
 WyRet \fBstat\fP(WyFileStat&) const
 virtual WyRet \fBreset\fP(void)
 virtual WyRet \fBreset\fP(const Wy_DirFile&)
 virtual WyRet \fBreset\fP(const char*)
 virtual WyRet \fBreset\fP(const WyStr&)
 virtual WyRet \fB_swap\fP(Wy_DirFile&) throw()
 virtual Wy_DirFile* \fB_alloc\fP(WyRet&) const
 virtual WyRet \fBread\fP(WyDirEnt&)
 virtual WyRet \fBrewind\fP(void)
 static WyRet \fBcreate\fP(const char*,mode_t)
 static WyRet \fBcreate\fP(const WyStr&,mode_t)
 static WyRet \fBunlink\fP(const char*)
 static WyRet \fBunlink\fP(const WyStr&)
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "Wy_DirFile()"
.PP
    Construct default object (refers to nothing)
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM  Not enough memory
.\"--------------------------------------------
.PP
.BI "Wy_DirFile(const Wy_DirFile& " "dirf" ")"
.PP
    Construct object to handle the system file handled by \fIdirf\fP.
.PP
    [\fBThrow\fP] Reply
            Wym_ENFILE  table overflow
            Wym_ENOMEM  Not enough memory
.\"--------------------------------------------
.PP
.BI "Wy_DirFile(const char* " "pathname" ")"
.PP
.BI "Wy_DirFile(const WyStr& " "pathname" ")"
.PP
    Construct object to handle the system file pointed by \fIpathname\fP
    The object is open O_RDONLY

    Note: Default(empty) \fIpathname\fP opens the current working directory.
.PP
    [\fBThrow\fP] Reply
            Wym_EACCES      Search permission is denied
            Wym_EBADF       File is not valid for the operation
            Wym_ENAMETOOLONG Pathname too long
            Wym_ENOENT      Pathname does not exist
            Wym_ENOTDIR     Entry in pathname is not a directory
            Wym_EMFILE      Too many open fd
            Wym_ENFILE      File table overflow
            Wym_ENOMEM      Not enough memory
            Wym_EEXIST      Pathname already exists
            Wym_EINTR       Interrupted by a signal
            Wym_ENOSPC      Device left no space for the operation
            Wym_ENXIO       No such device (device not ready)
            Wym_EROFS       Read-only file system
            Wym_ENODEV      No such device
            Wym_ELOOP       Too many symbolic links encountered
            ...             reply converted from ::open and
                            ::opendir
.PP 
    [\fBRefer\fP] ::open(const char*,int,mode_t),::opendir(const char*)
.\"--------------------------------------------
.PP
.BI "Wy_DirFile(Wy_DirFile& " "src" ", Wy::ByMove_t) throw()"
.PP
    See Wy_Array(Wy_Array&, Wy::ByMove_t) in wy_array(3wy)
    for definition of the move constructor.
.\"--------------------------------------------
.PP
.BI "virtual ~Wy_DirFile()"
.PP
    Destruct *this
.PP
    Note: errno from ::close(int) is ignored.

    Note: This member is non-cancellable.
.PP 
    [\fBRefer\fP] ::close(int), ::closedir(...)
.\"--------------------------------------------
.PP
.BI "bool is_default(void) const throw()"
.TP
    Is *this equivalent to the default object
.PP
    [\fBRet\fP] true= object is equivalent to the default one.
         false= otherwise
.\"--------------------------------------------
.PP
.BI "WyFileHandle fh(void) const throw()"
.PP
    Get the file handle of *this
.PP
    [\fBRet\fP] file handle which contains the exact file descriptor
          of *this
.\"--------------------------------------------
.PP
.BI "WyRet stat(WyFileStat& " "filestat" ") const" 
.PP
    Reset \fIfilestat\fP with the file information *this associates
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       Object is default
          Wym_ENOMEM      Not enough memory
          ...
.PP 
    [\fBRefer\fP] ::fstat(int,struct stat*)
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(void)" 
.PP
    Reconstruct *this to the state as Wy_DirFile()
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EIO         low level I/O error
          Wym_EINTR       a signal had occurred
          ...             reply converted from the returned errno of 
                          ::close and ::closedir
    
    Note: Object is always default while returned.
.PP 
    [\fBRefer\fP] ::close(int),::closedir(...)
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(const Wy_DirFile& " "dirf" ")" 
.PP
    Reconstruct *this to the state as Wy_DirFile(\fIdirf\fP)
.PP
    [\fBRet\fP] Ok              Succeed. Error report from closing the 
                          previously associated device is ignored
          Wym_ENFILE      File table overflow

    Note: Error report from closing the previously handled
          object is ignored. Use reset() first if the close
          return status is desired
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(const char* " "pathname" ")" 
.PP
.BI "virtual WyRet reset(const WyStr& " "pathname" ")" 
.PP
    Reconstruct *this to the state as Wy_DirFile(\fIpathname\fP)
    The object is open O_RDONLY

    Note: Default(empty) \fIpathname\fP opens the current working directory
.PP
    [\fBRet\fP] Ok              Succeed. Error report from closing the 
                          previously associated device is ignored
          Wym_EACCES      Search permission is denied
          Wym_EBADF       File is not valid for the operation
          Wym_ENAMETOOLONG Pathname too long
          Wym_ENOENT      Pathname does not exist
          Wym_ENOTDIR     A component in pathname is not a directory
          Wym_EMFILE      Too many open fd
          Wym_ENFILE      File table overflow
          Wym_ENOMEM      Not enough memory
          Wym_EEXIST      Pathname already exists
          Wym_EINTR       Interrupted by a signal
          Wym_ENOSPC      Device left no space for the operation
          Wym_ENXIO       No such device (device not ready)
          Wym_EROFS       Read-only file system
          Wym_ENODEV      No such device
          Wym_ELOOP       Too many symbolic links encountered
          ...             reply converted from the errno of ::open
                          and ::opendir

    Note: Error report from closing the previously handled
          object is ignored. Use reset() first if the close
          return status is desired
.PP 
    [\fBRefer\fP] ::open(const char*,int,mode_t),::opendir(const char*)
.\"--------------------------------------------
.PP
.BI "virtual WyRet _swap(Wy_DirFile& " "dirf" ") throw()"
.PP
    Interchange state of *this with \fIdirf\fP
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EBADTYPE    \fIdirf\fP is not the same type
.\"--------------------------------------------
.PP
.BI "virtual Wy_DirFile* _alloc(WyRet& " "r" ") const"
.PP
    Allocate a default object of the most inherited type that
    *this refers.

    Note: Inhertied class must override this member

    \fIr\fP is reset with the return status:
            Wym_ENOMEM      Not enough memory
            ...             Same from constructing Wy_DirFile()
.PP
    [\fBRet\fP] Pointer of the allocated object, or NULL if failed.
          User is responsible to \fBdelete\fP the returned object.
.\"--------------------------------------------
.PP
.BI "virtual WyRet read(WyDirEnt& " "dent" ")" 
.PP
    Read the directory entry and reset \fIdent\fP with the result.
    The next read begins with the next entry. \fIdent\fP is set to
    default if no more entry to read.
.PP
    [\fBRet\fP] Ok              Succeed. \fIdent\fP contains the
                          directory entry read.
          Wym_EBADF       Object is default
          .....           reply converted from ::readdir_r

    Note: Members read and rewind access exactly the same 
          information entity of the system among all other
          objects in different processes.
.PP 
    [\fBRefer\fP] ::readdir_r
.\"--------------------------------------------
.PP
.BI "virtual WyRet rewind(void)" 
.PP
    Set the next directory reading to the begin
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       Object is default

    Note: Members read and rewind access exactly the same 
          information entity of the system among all other
          objects in different processes.
.PP 
    [\fBRefer\fP] ::rewinddir
.\"--------------------------------------------
.PP
.BI "static WyRet create(const char* " "path" ",mode_t " "mode" ")"
.PP
.BI "static WyRet create(const WyStr& " "path" ",mode_t " "mode" ")"
.PP
    Create a new directory \fIpath\fP with permission \fImode\fP
    Argument \fImode\fP is a bitwise inclusive OR of the following values:
 
    S_IRUSR  the directory owner has read permission
    S_IWUSR  the directory owner may create files in the directory
    S_IXUSR  the directory may be serached by the owner
 
    S_IRGRP  directory owner's group member have read permission
    S_IWGRP  directory owner's group member may create new files
    S_IXGRP  directory owner's group member may search the directory
 
    S_IROTH  others has read permission
    S_IWOTH  others can create new files in the directory
    S_IXOTH  others can search the directory
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EACCESS     Access is not allowed
          Wym_EPERM       Operation not permitted
          Wym_EFAULT      \fIpath\fP is inaccessible
          Wym_EEXIST      \fIpath\fP already exist
          Wym_EMLINK      Number of links would exceed LINK_MAX
          Wym_ENAMETOOLONG \fIpath\fP too long
          Wym_ENOENT      A component in \fIpath\fP does not exist
          Wym_ENOSPC      No space left for \fIpath\fP
          Wym_ENOTDIR     A component in \fIpath\fP is not a directory
          Wym_EROFS       Refers to a file in a read-only filesystem
          Wym_ENOMEM      Not enough memory
          Wym_ELOOP       Too many symbolic encountered
          ....            reply converted from the errno ::mkdir
                          returned
 
    [\fBRefer\fP] ::mkdir(const char*,mode_t)
.\"--------------------------------------------
.PP
.BI "static WyRet unlink(const char* " "path" ")"
.PP
.BI "static WyRet unlink(const WyStr& " "path" ")"
.PP
    Remove a directory \fIpath\fP
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EACCESS     Access is not allowed
          Wym_EPERM       Operation not permitted
          Wym_EFAULT      \fIpath\fP is inaccessible
          Wym_ENAMETOOLONG \fIpath\fP too long
          Wym_ENOENT      A component in \fIpath\fP does not exist
          Wym_ENOTDIR     A component in \fIpath\fP is not a directory
          Wym_ENOTENPTY   \fIpath\fP contains entries other than . and ..
          Wym_EBUSY       \fIpath\fP is being used
          Wym_EROFS       Refers to a file in a read-only filesystem
          Wym_ENOMEM      Not enough memory
          Wym_ELOOP       Too many symbolic encountered
          ....            reply converted from the errno ::rmdir
                          returned
 
    [\fBRefer\fP] ::rmdir(const char*)
.\"--------------------------------------------
.SH "SEE ALSO"
.BR wyret
.BR wydirent
.BR wyfilestat
.BR wyregfile
.BR wychrfile
.BR wy
.BR wymutex
.BR wytimespec
.SH NOTE
Except added by this library, replys are converted from the errno 
an underlying C library function returned. Report of such replys
are brief from Linux Programmer's Manual. See the associated man page
for details.

Project is in development, http://sourceforge.net/projects/libwx