workbench/network/stacks/AROSTCP/bsdsocket/api/auto_extras.c

   1 /****** bsdsocket.library/Errno *********************************************
   2 *
   3 *   NAME
   4 *        Errno - get error value after unsuccessful function call
   5 *
   6 *   SYNOPSIS
   7 *        errno = Errno()
   8 *        D0
   9 *
  10 *        LONG Errno(VOID);
  11 *
  12 *   FUNCTION
  13 *        When  some  function  in  socket  library  return  an  error
  14 *        condition value, they also set a specific error value.  This
  15 *        error value can be extracted by this function.
  16 *
  17 *   RESULT
  18 *        Error value  indicating  the error on  last failure  of some
  19 *        socket function call.
  20 *
  21 *   NOTES
  22 *        Return  value  of  Errno()  is not changed  after successful
  23 *        function so it cannot be used to determine success of any
  24 *        function call  of this library.  Also, another function call
  25 *        to this  library may change  the return value of  Errno() so
  26 *        use it right after error occurred.
  27 *
  28 *   SEE ALSO
  29 *        SetErrnoPtr()
  30 *
  31 *****************************************************************************
  32 *
  33 */
  34
  35
  36 /****** bsdsocket.library/ObtainSocket **************************************
  37 *
  38 *   NAME
  39 *        ObtainSocket - get a socket from AmiTCP/IP socket list
  40 *
  41 *   SYNOPSIS
  42 *        s = ObtainSocket(id, domain, type, protocol)
  43 *        D0               D0  D1      D2    D3
  44 *
  45 *        LONG ObtainSocket(LONG, LONG, LONG, LONG);
  46 *
  47 *   FUNCTION
  48 *        When one task wants to give  a socket to  an another one, it
  49 *        releases it (with a key value) to a special socket list held
  50 *        by  AmiTCP/IP.   This  function  requests  that  socket  and
  51 *        receives it if id and other parameters match.
  52 *
  53 *   INPUTS
  54 *        id       - a key value given by the socket donator.
  55 *        domain   - see documentation of socket().
  56 *        type     - see documentation of socket().
  57 *        protocol - see documentation of socket().
  58 *
  59 *   RESULT
  60 *        Non negative socket descriptor on success. On failure, -1 is
  61 *        returned and the errno is set to indicate the error.
  62 *
  63 *   ERRORS
  64 *        EMFILE          - The per-process descriptor table is
  65 *                          full.
  66 *
  67 *        EPROTONOSUPPORT - The protocol type or the specified  pro-
  68 *                          tocol is not supported within this
  69 *                          domain.
  70 *
  71 *        EPROTOTYPE      - The protocol is the wrong type for the
  72 *                          socket.
  73 *
  74 *        EWOULDBLOCK     - Matching socket is not found.
  75 *
  76 *   SEE ALSO
  77 *        ReleaseCopyOfSocket(), ReleaseSocket(), socket()
  78 *
  79 *****************************************************************************
  80 *
  81 */
  82
  83 /****** bsdsocket.library/ReleaseCopyOfSocket *******************************
  84 *
  85 *   NAME
  86 *        ReleaseCopyOfSocket - copy given socket to AmiTCP/IP socket list.
  87 *
  88 *   SYNOPSIS
  89 *        id = ReleaseCopyOfSocket(fd, id)
  90 *        D0                       D0  D1
  91 *
  92 *        LONG ReleaseCopyOfSocket(LONG, LONG);
  93 *
  94 *   FUNCTION
  95 *        Make a new reference to a given socket (pointed by its descriptor)
  96 *        and release it to the socket list held by AmiTCP/IP.
  97 *
  98 *   INPUTS
  99 *        fd - descriptor of the socket to release.
 100 *
 101 *        id - the key value to identify use of this socket. It can be
 102 *             unique or not, depending on its  value.  If id value is
 103 *             between 0  and  65535,  inclusively,  it is  considered
 104 *             nonunique  and it can  be  used as a port  number,  for
 105 *             example.   If  id is greater  than  65535 and less than
 106 *             2^31) it  must be unique in currently  held sockets  in
 107 *             AmiTCP/IP socket  list,  Otherwise  an  error  will  be
 108 *             returned  and  socket  is  not  released.    If  id  ==
 109 *             UNIQUE_ID (defined in <sys/socket.h>) an unique id will
 110 *             be generated.
 111 *
 112 *   RESULT
 113 *        id - -1 in case of error and the key value of the socket put
 114 *             in the list. Most useful when an unique id is generated
 115 *             by this routine.
 116 *
 117 *   ERRORS
 118 *        EINVAL - Requested unique id is already used.
 119 *
 120 *        ENOMEM - Needed memory couldn't be allocated.
 121 *
 122 *   NOTE
 123 *        The socket descriptor is not deallocated.
 124 *
 125 *   SEE ALSO
 126 *        ObtainSocket(), ReleaseSocket()
 127 *
 128 *
 129 *****************************************************************************
 130 *
 131 */
 132
 133 /****** bsdsocket.library/ReleaseSocket *************************************
 134 *
 135 *   NAME
 136 *        ReleaseSocket - release given socket to AmiTCP/IP socket list.
 137 *
 138 *   SYNOPSIS
 139 *        id = ReleaseSocket(fd, id)
 140 *        D0                 D0  D1
 141 *
 142 *        LONG ReleaseSocket(LONG, LONG);
 143 *
 144 *   FUNCTION
 145 *        Release the reference of given socket (via  its  descriptor)
 146 *        and move the socket to the  socket  list held by  AmiTCP/IP.
 147 *        The socket descriptor is deallocated in this procedure.
 148 *
 149 *   INPUTS
 150 *        fd - descriptor of the socket to release.
 151 *
 152 *        id - the key value to identify use of this socket. It can be
 153 *             unique or not, depending on its  value.  If id value is
 154 *             between 0  and  65535,  inclusively,  it is  considered
 155 *             nonunique  and it can  be  used as a port  number,  for
 156 *             example.   If  id is greater  than  65535 and less than
 157 *             2^31) it  must be unique in currently  held sockets  in
 158 *             AmiTCP/IP socket  list,  Otherwise  an  error  will  be
 159 *             returned  and  socket  is  not  released.    If  id  ==
 160 *             UNIQUE_ID (defined in <sys/socket.h>) an unique id will
 161 *             be generated.
 162 *
 163 *   RESULT
 164 *        id - -1 in case of error and the key value of the socket put
 165 *             in the list. Most useful when an unique id is generated
 166 *             by this routine.
 167 *
 168 *   ERRORS
 169 *        EINVAL - Requested unique id is already used.
 170 *
 171 *        ENOMEM - Needed memory couldn't be allocated.
 172 *
 173 *   SEE ALSO
 174 *        ObtainSocket(), ReleaseCopyOfSocket()
 175 *
 176 *****************************************************************************
 177 *
 178 */
 179
 180 /****** bsdsocket.library/SetErrnoPtr ***************************************
 181 *
 182 *   NAME
 183 *        SetErrnoPtr - set new place where the error value will be written
 184 *
 185 *   SYNOPSIS
 186 *        SetErrnoPtr(ptr, size)
 187 *                    A0   D0
 188 *
 189 *        VOID SetErrnoPtr(VOID *, UBYTE);
 190 *
 191 *   FUNCTION
 192 *        This functions allows caller to redirect error variable inside
 193 *        scope of  caller task.   Usually this is  used to make  task's
 194 *        global variable errno as error variable.
 195 *
 196 *   INPUTS
 197 *        ptr     - pointer to error variable that is to be modified on
 198 *                  every error condition on this library function.
 199 *        size    - size of the error variable.
 200 *
 201 *   EXAMPLE
 202 *        #include <errno.h>
 203 *
 204 *        struct Library;
 205 *        struct Library * SocketBase = NULL;
 206 *
 207 *        int main(void)
 208 *        {
 209 *           ...
 210 *          if ((SocketBase = OpenLibrary("bsdsocket.library", 2))
 211 *              != NULL) {
 212 *            SetErrnoPtr(&errno, sizeof(errno));
 213 *           ...
 214 *          }
 215 *        }
 216 *
 217 *   NOTES
 218 *        Be sure that this new error variable exists until library base
 219 *        is finally closed or SetErrnoPtr() is called again for another
 220 *        variable.
 221 *
 222 *   SEE ALSO
 223 *        Errno()
 224 *
 225 *****************************************************************************
 226 *
 227 */
 228
 229 /****** bsdsocket.library/SetSocketSignals **********************************
 230 *
 231 *   NAME
 232 *        SetSocketSignals - inform AmiTCP/IP of INTR, IO and URG signals
 233 *
 234 *   SYNOPSIS
 235 *        SetSocketSignals(sigintrmask, sigiomask, sigurgmask)
 236 *                         D0           D1         D2
 237 *
 238 *        VOID SetSocketSignals(ULONG, ULONG, ULONG);
 239 *
 240 *   FUNCTION
 241 *        SetSocketSignals() tells  the  AmiTCP/IP which signal  masks
 242 *        corresponds UNIX SIGINT, SIGIO and SIGURG signals to be used
 243 *        in   this implementation.  The  sigintrmask  mask is used to
 244 *        determine which  Amiga  signals interrupt  blocking  library
 245 *        calls.
 246 *
 247 *        The sigiomask  is sent  when  asynchronous  notification  of
 248 *        socket   events   is  done,  the sigurgmask    is  sent when
 249 *        out-of-band   data  arrives, respectively.   The signals are
 250 *        sent only  to  the owning task  of   particular socket.  The
 251 *        socket  has got no owner   by default; the  owner  is set by
 252 *        FIOSETOWN (SIOCSPGRP) ioctl call.
 253 *
 254 *        Note that the supplied  values write over  old ones. If this
 255 *        function is used and CTRL-C is still wanted to interrupt the
 256 *        calls (the default behaviour),  the value BREAKF_CTRL_C must
 257 *        be explicitly given.
 258 *
 259 *   NOTES
 260 *        The function SetSocketSignals() is obsoleted by the function
 261 *        SocketBaseTags().
 262 *
 263 *   SEE ALSO
 264 *        IoctlSocket(), recv(), send(), select(), WaitSelect()
 265 *
 266 *****************************************************************************
 267 *
 268 */