wysysfile.3wy

一个不错

.\"
.\" Edited by I.J.Wang, 2004
.\"
.TH WySysFile 3wy "libwy v0.31"
.SH NAME
WySysFile \- base handle class of system file
.SH SYNOPSIS
.B #include <wysysfile.h>
.PP
WySysFile is the base handle class of system file
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 \fBWySysFile\fP()
 \fBWySysFile\fP(WyFileHandle)
 \fBWySysFile\fP(const WySysFile&)
 \fBWySysFile\fP(WySysFile&, Wy::ByMove_t) throw()
 virtual \fB~WySysFile\fP()
 bool \fBis_default\fP(void) const throw()
 WyFileHandle \fBfh\fP(void) const throw()
 mode_t \fBftype\fP(void) const throw()
 WyRet \fBstat\fP(WyFileStat&) const
 virtual WyRet \fBreset\fP(void)
 virtual WyRet \fBreset\fP(WyFileHandle)
 virtual WyRet \fBreset\fP(const WySysFile&)
 virtual WyRet \fB_swap\fP(WySysFile&) throw()
 virtual WySysFile* \fB_alloc\fP(WyRet&) const
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet
.PP
    Class specific throw type.
.\"--------------------------------------------
.PP
.BI "WySysFile()"
.PP
    Construct default object (nothing)

     fh()   = WyFileHandle()
     ftype()= 0
.PP
    [\fBThrow\fP] Reply
            (reserved)
.\"--------------------------------------------
.PP
.BI "WySysFile(WyFileHandle " "h" ")" 
.PP
    Construct object to handle the system file handled by \fIh\fP

     fh()   = contains file descriptor ::dup from \fIh\fP
     ftype()= file type of \fIh\fP
.PP
    [\fBThrow\fP] Reply
            Wym_EBADF       \fIh\fP is not valid for the operation
            Wym_EMFILE      Too many open fd
            Wym_ENOMEM      Not enough memory
.PP 
    [\fBRefer\fP] ::dup(int)
.\"--------------------------------------------
.PP
.BI "WySysFile(const WySysFile& " "sysf" ")"
.PP
    Construct object to handle the system file handled by \fIsysf\fP

     fh()   = contains file descriptor ::dup from \fIsysf\fP
     ftype()= \fIsysf\fP.ftype()
.PP
    [\fBThrow\fP] Reply
            Wym_EMFILE  too many open devices
            Wym_ENOMEM  Not enough memory
.PP 
    [\fBRefer\fP] ::dup(int)
.\"--------------------------------------------
.PP
.BI "WySysFile(WySysFile& " "src" ", Wy::ByMove_t) throw()"
.PP
    Make the object \fIsrc\fP accessible at \fIthis\fP pointed address.

    After function completed, \fIsrc\fP is just regarded non-existant
    without destructor being called and can not be, and the space
    occupied can be recycled. The dummy argument type ByMove_t is
    for function signature, use instance should always be Wy::ByMove.
    This member is supposed to be invoked only via placement new an in
    member initialization list, not to be explicitly called.

    This member is not entirely a real constructor (no new object is
    ever created) but a function in constructor form to support object
    movement in a dynamic array.

    Note: Except in member initialization list, \fIsrc\fP must be
          a whole type, not reference to a base. Otherwise,
          effect is undefined.

    [\fBEffect\fP]
            fh()   = \fIsrc\fP.fh()
            ftype()= \fIsrc\fP.ftype()

            At final, object \fIsrc\fP does not exist
.\"--------------------------------------------
.PP
.BI "virtual ~WySysFile()"
.PP
    Destruct *this.
.PP
    Note: errno from ::close(int) is ignored.

    Note: This member is non-cancellable.
.PP 
    [\fBRefer\fP] ::close(int)
.\"--------------------------------------------
.PP
.BI "bool is_default(void) const throw()"
.PP
    Is *this equivalent to the default object
.PP
    [\fBRet\fP] true= object is equivalent to WySysFile().
         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 "mode_t ftype(void) const throw()"
.PP
    Get file type of the system file *this is associated 
.PP
    [\fBRet\fP] File type of *this associated system file

          0        Default object
          S_IFREG  Regular file
          S_IFCHR  Character device
          S_IFSOCK Socket
          S_IFIFO  Fifo
          S_IFDIR  Directory file (reserved)
          S_IFLNK  Symbolic link  (reserved)
          S_IFBLK  Block device   (reserved)
.\"--------------------------------------------
.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 not valid for the operation
          Wym_ENOMEM      Not enough memory
          ...
.PP 
    [\fBRefer\fP] ::fstat(int,struct stat*)
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(void)" 
.PP
    Reset *this to the state as WySysFile()
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EIO         low level I/O error
          Wym_EINTR       a signal had occurred
          ...             reply converted from the errno ::close 
                          returned
    
    Note: Object is always default while returned.
.PP 
    [\fBRefer\fP] ::close(int)
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(WyFileHandle " "h" ")" 
.PP
    Reconstruct *this to the state as WySysFile(\fIh\fP)
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       \fIh\fP is not valid for the operation
          Wym_EMFILE      Too many open fd

          (If *this is a standard i/o handler,
           the following errors may also occur)

          Wym_EINTR       A signal had occurred
          Wym_EBUSY       Device or resource busy

    Note: Error report from closing the previously handled
          object is ignored. Use reset() first if the close
          return status is desired
.PP 
    [\fBRefer\fP] ::dup(int), ::dup2(int,int)
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(const WySysFile& " "sysf" ")" 
.PP
    Reconstruct *this to the state as WySysFile(sysf)
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       \fIsysf\fP not valid for the operation
          Wym_EMFILE      too many open devices

          (If *this is a standard i/o handler,
           the following errors may also occur)

          Wym_EINTR       A signal had occurred
          Wym_EBUSY       Device or resource busy

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

    Note: Inhertied class must override this member
          See man. wybyteflow(3wy) for the reimpement example.

    \fIr\fP is reset with the return status:
            Wym_ENOMEM      Not enough memory
            Wym_ENOSYS      *Not overridden
            ...             Same from constructing WySysFile()
.PP
    [\fBRet\fP] Pointer of the allocated object, or NULL if failed.
          User is responsible to \fBdelete\fP the returned object.
.\"--------------------------------------------
.SH "SEE ALSO"
.BR wybyteflow
.BR wyregfile
.BR wychrfile
.BR wysockfile
.BR wyfifofile
.BR wyterminal
.BR wy_dirfile
.BR wy_lnkfile
.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