wysockfile.3wy

一个不错

.TH WySockFile 3wy "libwy v0.31"
.SH NAME
WySockFile \- handle class for system socket file
.SH SYNOPSIS
.B #include <wysockfile.h>
.PP
[\fBInherit\fP] WyByteFlow
.PP
WySockFile is a handle class for the system socket file
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 \fBWySockFile\fP()
 \fBWySockFile\fP(WyFileHandle)
 \fBWySockFile\fP(const WySysFile&)
 \fBWySockFile\fP(int,int,int=0)
 \fBWySockFile\fP(const WySockFile&)
 \fBWySockFile\fP(WySockFile&, Wy::ByMove_t) throw()
 virtual \fB~WySockFile\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(int,int,int=0)
 virtual WyRet \fB_swap\fP(WySysFile&) throw()
 virtual WySockFile* \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&)

 int \fBfamily\fP(void) const throw()
 WyRet \fBsockname\fP(Wy_SockAddr&) const
 WyRet \fBpeername\fP(Wy_SockAddr&) const
 virtual WyRet \fBshutdown\fP(int)
 virtual WyRet \fBbind\fP(const Wy_SockAddr&)
 virtual WyRet \fBlisten\fP(int)
 virtual WyRet \fBaccept\fP(WySockFile&,Wy_SockAddr&)
 virtual WyRet \fBconnect\fP(const Wy_SockAddr&)
 virtual WyRet \fBsendto\fP(const void*,size_t,int,
                      const Wy_SockAddr*,size_t&)
 virtual WyRet \fBrecvfrom\fP(void*,size_t,int,Wy_SockAddr*,size_t&)
 static WyRet \fBsockpair\fP(int,int,int,WySockFile&,WySockFile&)
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "WySockFile()"
.PP
    Construct default object (refers to nothing)

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

     fh()    = contains file descriptor ::dup from \fIh\fP
     family()= derived from ::getsockname 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 "WySockFile(const WySysFile& " "sktf" ")"
.PP
    Construct object to handle the system file handled by \fIsktf\fP.

     fh()    = contains file descriptor ::dup from \fIsktf\fP
     family()= \fIsktf\fP.family()
.PP
    [\fBThrow\fP] Reply
            Wym_EBADF   \fIsktf\fP is not valid for the operation
            Wym_EMFILE  Too many open system files
            Wym_ENOMEM  Not enough memory
.PP 
    [\fBRefer\fP] ::dup(int)
.\"--------------------------------------------
.PP
.BI "WySockFile(int " "domain" ", int " "type" ", int " "proto=0" ")" 
.PP
    Construct object to handle the system file designated for
    communication of the arguments given protocol.

      \fIdomain\fP = PF_LOCAL| PF_INET| ...
      \fItype\fP   = SOCK_STREAM| SOCK_DGRAM| ...
      \fIproto\fP  = protocol number of the socket (See /etc/protocols)

     fh()    = contains file descriptor from 
               ::socket(\fIdomain\fP,\fItype\fP,\fIproto\fP)
     family()= \fIdomain\fP
.PP
    [\fBThrow\fP] Reply
            Wym_EPROTONOSUPPORT protocol is not supported
            Wym_EAFNOSUPPORT Address family not supported by protocol 
            Wym_ENFILE      File table overflow
            Wym_EMFILE      Too many open fd
            Wym_EACCES      Search permission is denied
            Wym_ENOMEM      Not enough memory
            Wym_EINVAL      Invalid argument 
            ...             reply converted from ::socket
.PP 
    [\fBRefer\fP] ::socket(int,int,int)
.\"--------------------------------------------
.PP
.BI "WySockFile(const WySockFile& " "sktf" ")"
.PP
    Construct object to handle the system file handled by \fIsktf\fP.

     fh()    = contains file descriptor ::dup from \fIsktf\fP
     family()= \fIsktf\fP.family()
.PP
    [\fBThrow\fP] Reply
            Wym_EMFILE  Too many open system files
            Wym_ENOMEM  Not enough memory
.PP 
    [\fBRefer\fP] ::dup(int)
.\"--------------------------------------------
.PP
.BI "WySockFile(WySockFile& " "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 ~WySockFile()"
.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 WySockFile().
         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 WySockFile()
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EINTR       a signal had occurred
          Wym_EIO         low level I/O error
          ...             reply converted from the returned errno
                          of ::close
    
    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 WySockFile(\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& " "sktf" ")" 
.PP
    Reconstruct *this to the state as WySockFile(\fIsktf\fP)
.PP
    [\fBRet\fP] Ok              Succeed.
          Wym_EBADF       \fIsktf\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(int " "domain" ", int " "type" ", int " "proto=0" ")" 
.PP
    Reconstruct *this to the state as WySockFile(\fIdomain\fP,\fItypef\fP,\fIproto\fP)

      \fIdomain\fP= PF_LOCAL| PF_INET| ...
      \fItype\fP  = SOCK_STREAM| SOCK_DGRAM| ...
      \fIproto\fP = protocol number of the socket (See /etc/protocols)
.PP
    [\fBRet\fP] Ok              Succeed. Error report from closing the 
                          previously associated device is ignored
          Wym_EPROTONOSUPPORT protocol is not supported
          Wym_EAFNOSUPPORT Address family not supported by protocol 
          Wym_ENFILE      File table overflow
          Wym_EMFILE      Too many open fd
          Wym_EACCES      Search permission is denied
          Wym_ENOMEM      Not enough memory
          Wym_EINVAL      Invalid argument 
          ...             reply converted from the errno of ::socket

    Note: Error report from closing the previously handled
          object is ignored. Use reset() first if the close
          return status is desired
.PP 
    [\fBRefer\fP] ::socket(int,int,int)
.\"--------------------------------------------
.PP
.BI "virtual WyRet _swap(WySysFile& " "sktf" ") throw()"
.PP
    Interchange state of *this with \fIsktf\fP
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EBADTYPE    \fIsktf\fP is not the same type
.\"--------------------------------------------
.PP
.BI "virtual WySockFile* _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 WySockFile()
.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" ")"