wyregfile.3wy

一个不错

.\"
.\" Edited by I.J.Wang, 2004
.\"
.TH WyRegFile 3wy "libwy v0.31"
.SH NAME
WyRegFile \- handle class of system regular file
.SH SYNOPSIS
.B #include <wyregfile.h>
.PP
[\fBInherit\fP] WyByteFlow
.PP
WyRegFile is a handle class for the system regular file
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 \fBWyRegFile\fP()
 \fBWyRegFile\fP(WyFileHandle)
 \fBWyRegFile\fP(const WySysFile&)
 \fBWyRegFile\fP(const char*,int)
 \fBWyRegFile\fP(const WyStr&,int)
 \fBWyRegFile\fP(const WyRegFile&)
 \fBWyRegFile\fP(WyRegFile&, Wy::ByMove_t) throw()
 virtual \fB~WyRegFile\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(WyFileHandle)
 virtual WyRet \fBreset\fP(const WySysFile&)
 virtual WyRet \fBreset\fP(const char*,int)
 virtual WyRet \fBreset\fP(const WyStr&,int)
 virtual WyRet \fB_swap\fP(WySysFile&) throw()
 virtual WyRegFile* \fB_alloc\fP(WyRet&) const
 virtual WyRet \fBread\fP(void*,size_t,size_t&)
 virtual WyRet \fBread\fP(WyStr&,size_t,size_t&)
 virtual WyRet \fBwrite\fP(const void*, size_t,size_t&)
 virtual WyRet \fBwrite\fP(WyCSeg,size_t&)
 virtual WyRet \fBwrite\fP(const WyStr&,size_t&)
 virtual WyRet \fBfsync\fP(void)
 virtual WyRet \fBfdatasync\fP(void)
 off_t \fBpos\fP(void) const
 virtual void \fBset_pos\fP(off_t)
 virtual WyRet \fBseek_end\fP(void)
 virtual WyRet \fBresize\fP(off_t)
 virtual WyRet \fB_read_till\fP(void*,size_t,size_t&,char)
 virtual WyRet \fB_read_till\fP(WyStr&,size_t,size_t&,char)

 static WyRet \fBcreate\fP(WyRegFile&,const char*,int,mode_t)
 static WyRet \fBcreate\fP(WyRegFile&,const WyStr&,int,mode_t)
 static WyRet \fBcreate_tmpfile\fP(WyRegFile&,WyStr&)
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "WyRegFile()"
.PP
    Construct default object (refers to nothing)

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

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

     fh() = contains file descriptor ::dup from \fIregf\fP
     pos()= \fIregf\fP.pos()
.PP
    [\fBThrow\fP] Reply
            Wym_EBADF   \fIregf\fP is not valid for the operation
            Wym_EMFILE  Too many open files
            Wym_ENOMEM  Not enough memory
.PP 
    [\fBRefer\fP] ::dup(int)
.\"--------------------------------------------
.PP
.BI "WyRegFile(const char* " "pathname" ",int " "f" ")"
.PP
.BI "WyRegFile(const WyStr& " "pathname" ",int " "f" ")"
.PP
    Construct object to handle the system file pointed by
    \fIpathname\fP with flags \fIf\fP

      \fIf\fP= flags for ::open, except O_CREAT

     fh() = contains file descriptor from ::open(\fIpathname\fP,\fIf\fP)
     pos()= 0
.PP
    [\fBThrow\fP] Reply
            Wym_EACCES      Search permission is denied
            Wym_EINVAL      \fIf\fP invalid
            Wym_EBADF       File is not valid for the operation
            Wym_ENAMETOOLONG \fIpathname\fP too long
            Wym_ENOENT      \fIpathname\fP does not exist
            Wym_ENOTDIR     Entry in \fIpathname\fP 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
.PP 
    [\fBRefer\fP] ::open(const char*,int,mode_t)
.\"--------------------------------------------
.PP
.BI "WyRegFile(const WyRegFile& " "regf" ")"
.PP
    Construct object to handle the system file handled by \fIregf\fP.

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

    See Wy_Array(Wy_Array&, Wy::ByMove_t) in wy_array(3wy)
    for definition of the move constructor.
.\"--------------------------------------------
.PP
.BI "virtual ~WyRegFile()"
.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()"
.TP
    Is *this equivalent to the default object
.PP
    [\fBRet\fP] true= object is equivalent to WyRegFile().
         false= otherwise
.\"--------------------------------------------
.PP
.BI "WyFileHandle fh(void) const throw()"
.TP
    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 not valid for the operation
          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 WyRegFile()
.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 or reimplemented function
    
    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 WyRegFile(\fIh\fP)
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       \fIh\fP is not valid for the operation
          Wym_EMFILE      Too many open fd

    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)
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(const WySysFile& " "regf" ")" 
.PP
    Reconstruct *this to the state as WyRegFile(\fIregf\fP)
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       \fIregf\fP is not valid for the operation
          Wym_EMFILE      Too many open fd

    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)
.\"--------------------------------------------
.PP
.BI "virtual WyRet reset(const char* " "pathname" ",int " "f" ")"
.PP
.BI "virtual WyRet reset(const WyStr& " "pathname" ",int " "f" ")"
.PP
    Reconstruct *this to the state as WyRegFile(\fIpathname\fP,\fIf\fP)

      \fIf\fP= flags for ::open, except O_CREAT
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EINVAL      \fIf\fP invalid
          Wym_EBADF       File is not valid for the operation
          Wym_EACCES      Search permission is denied
          Wym_ENAMETOOLONG \fIpathname\fP too long
          Wym_ENOENT      \fIpathname\fP does not exist
          Wym_ENOTDIR     Entry in \fIpathname\fP 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

    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)
.\"--------------------------------------------
.PP
.BI "virtual WyRet _swap(WySysFile& " "regf" ") throw()"
.PP
    Interchange state of *this with \fIregf\fP
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EBADTYPE    \fIregf\fP is not the same type
.\"--------------------------------------------
.PP
.BI "virtual WyRegFile* _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 WyRegFile()