wychrfile.3wy

一个不错

.\"
.\" Edited by I.J.Wang, 2004
.\"
.TH WyChrFile 3wy "libwy v0.31"
.SH NAME
WyChrFile \- handle class of system character file
.SH SYNOPSIS
.B #include <wychrfile.h>
.PP
[\fBInherit\fP] WyByteFlow
.PP
WyChrFile is a handle class for the system character file
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 \fBWyChrFile\fP()
 \fBWyChrFile\fP(WyFileHandle)
 \fBWyChrFile\fP(const WySysFile&)
 \fBWyChrFile\fP(const char*,int)
 \fBWyChrFile\fP(const WyStr&,int)
 \fBWyChrFile\fP(const WyChrFile&)
 \fBWyChrFile\fP(WyChrFile&, Wy::ByMove_t) throw()
 virtual \fB~WyChrFile\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 WyChrFile* \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&)

 WyRet \fB_tcdrain\fP(void)
 bool \fB_isatty\fP(void) const
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "WyChrFile()"
.PP
    Construct default object (refers to nothing)

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

     fh()= contains file descriptor ::dup from \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 "WyChrFile(const WySysFile& " "chrf" ")"
.PP
    Construct object to handle the system file handled by \fIchrf\fP

     fh()= contains file descriptor ::dup from \fIchrf\fP
.PP
    [\fBThrow\fP] Reply
            Wym_EBADF   \fIchrf\fP is not valid for the operation
            Wym_EMFILE  Too many open devices
            Wym_ENOMEM  Not enough memory
.PP 
    [\fBRefer\fP] ::dup(int)
.\"--------------------------------------------
.PP
.BI "WyChrFile(const char* " "pathname" ",int " "f" ")" 
.PP
.BI "WyChrFile(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)
.PP
    [\fBThrow\fP] Reply
            Wym_EACCES      Search permission is denied 
            Wym_EBADF       File is not valid for the operation
            Wym_EINVAL      \fIf\fP invalid
            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)
.\"--------------------------------------------
.PP
.BI "WyChrFile(const WyChrFile& " "chrf" ")"
.PP
    Construct object to handle the system file handled by \fIchrf\fP

     fh()= contains file descriptor ::dup from \fIchrf\fP
.PP
    [\fBThrow\fP] Reply
            Wym_EMFILE  Too many open devices
            Wym_ENOMEM  Not enough memory
.PP 
    [\fBRefer\fP] ::dup(int)
.\"--------------------------------------------
.PP
.BI "WyChrFile(WyChrFile& " "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 ~WyChrFile()"
.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 WyChrFile().
         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 WyChrFile()
.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 WyChrFile(\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& " "chrf" ")"
.PP
    Reconstruct *this to the state as WyChrFile(\fIchrf\fP)
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       \fIchrf\fP is not valid for the operation
          Wym_EMFILE      Too many open devices

    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 WyChrFile(\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)
.\"--------------------------------------------
.PP
.BI "virtual WyRet _swap(WySysFile& " "chrf" ") throw()"
.PP
    Interchange state of *this with \fIchrf\fP
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EBADTYPE    \fIchrf\fP is not the same type as *this
.\"--------------------------------------------
.PP
.BI "virtual WyChrFile* _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 WyChrFile()
.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(void* " "buf" ", size_t " "count" ", size_t& " "n_read" ")"
.PP
    Read at most \fIcount\fP bytes of data into memory pointed by \fIbuf\fP.

    \fIn_read\fP is always written with the bytes read and stored
    into \fIbuf\fP.
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       Object is not valid for the operation
          Wym_EFBIG       \fIcount\fP exceeds the maximum
          Wym_EINTR       Interrupted by a signal before any data read
          Wym_EAGAIN      Non-blocking I/O (no data read)
          Wym_EIO         Low level I/O error
          Wym_EINVAL      Device is not suitable for reading
          Wym_EFAULT      \fIbuf\fP is inaccessible
          Wym_ENOMEM      Not enough memory for \fIcount\fP
.PP 
    [\fBRefer\fP] ::read(int,void*,size_t)
.\"--------------------------------------------
.PP
.BI "virtual WyRet read(WyStr&" " buf" ", size_t " "count" ", size_t& " "n_read" ")"
.PP
    Read at most \fIcount\fP bytes of data and \fBappend\fP to \fIbuf\fP.

    \fIn_read\fP is always written with the bytes read and appended
    to \fIbuf\fP.
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       Object is not valid for the operation
          Wym_EFBIG       \fIcount\fP exceeds the maximum
          Wym_EINTR       Interrupted by a signal before any data read
          Wym_EAGAIN      Non-blocking I/O (no data read)
          Wym_EIO         Low level I/O error
          Wym_EINVAL      Device is not suitable for reading
          Wym_ENOMEM      Not enough memory for \fIcount\fP
.PP 
    [\fBRefer\fP] ::read(int,void*,size_t)
.\"--------------------------------------------
.PP
.BI "virtual WyRet write(const void* " "buf" ", size_t " "count" ", size_t& " "n_written" ")"
.PP
    Write \fIcount\fP bytes of data in \fIbuf\fP to the system file

    The number of written bytes is always stored into \fIn_written\fP
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EBADF       Object is not valid for the operation
          Wym_EINVAL      Object attatched device is not suitable
          Wym_EFAULT      \fIbuf\fP is inaccessible
          Wym_EFBIG       Attempt to write beyond the device limit 
          Wym_EAGAIN      Non-blocking I/O (write would block)
          Wym_EINTR       Interrupted by a signal before data written
          Wym_ENOSPC      Device left no space for the operation
          Wym_EIO         Low level I/O error
.PP 
    [\fBRefer\fP] ::write(int,const void*,size_t)
.\"--------------------------------------------
.PP
.BI "virtual WyRet write(WyCSeg " "buf" ", size_t& " "n_written" ")"
.PP
    Write data indicated by \fIbuf\fP to the system file

    The number of written bytes is always stored into \fIn_written\fP
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EBADF       Object is not valid for the operation
          Wym_EINVAL      Object attatched device is not suitable
          Wym_EFBIG       Attempt to write beyond the device limit 
          Wym_EAGAIN      Non-blocking I/O (write would block)
          Wym_EINTR       Interrupted by a signal before data written
          Wym_ENOSPC      Device left no space for the operation
          Wym_EIO         Low level I/O error
.PP 
    [\fBRefer\fP] ::write(int,const void*,size_t)
.\"--------------------------------------------
.PP
.BI "virtual WyRet write(const WyStr& " "buf" ", size_t& " "n_written" ")"
.PP
    Write data in \fIbuf\fP to the system file

    The number of written bytes is always stored into \fIn_written\fP
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EBADF       Object is not valid for the operation
          Wym_EINVAL      Object attatched device is not suitable
          Wym_EFBIG       Attempt to write beyond the device limit 
          Wym_EAGAIN      Non-blocking I/O (write would block)
          Wym_EINTR       Interrupted by a signal before data written
          Wym_ENOSPC      Device left no space for the operation
          Wym_EIO         Low level I/O error
.PP 
    [\fBRefer\fP] ::write(int,const void*,size_t)
.\"--------------------------------------------
.PP
.BI "WyRet _tcdrain(void)" 
.PP
    Wait until all output written to *this associated terminal device
    has been transmitted.
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       Object is not valid for the operation
          Wym_EINTR       Interrupted by a signal
          Wym_ENOTTY      Not a terminal device
          ...             reply converted from the errno ::tcdrain
                          returned
.PP 
    [\fBRefer\fP] ::tcdrain(int)
.\"--------------------------------------------
.PP
.BI "bool _isatty(void) const" 
.PP
    Is *this referring to a terminal device
.PP
    [\fBRet\fP] true= *this refers to a terminal
         false= otherwise
.PP 
    [\fBRefer\fP] ::isatty(int)
.\"--------------------------------------------
.PP
.SH "SEE ALSO"
.BR wyret
.BR wybyteflow
.BR wystr
.BR wyterminal
.BR wyregfile
.BR wy
.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