NAME

       ns_sockaccept,     ns_sockblocking,    ns_sockcallback,    ns_sockcheck,    ns_socketpair,
       ns_socklisten,  ns_socklistencallback,  ns_socknonblocking,   ns_socknread,   ns_sockopen,
       ns_sockselect - Network socket commands

SYNOPSIS

       ns_sockaccept sockid

       ns_sockblocking sockid

       ns_sockcallback sockid script when

       ns_sockcheck fileid

       ns_socketpair

       ns_socklisten address port

       ns_socklistencallback address port script

       ns_socknonblocking sockid

       ns_socknread sockid

       ns_sockopen ?-nonblock | -timeout seconds? host port

       ns_sockselect ?-timeout seconds? rfds wfds efds
_________________________________________________________________

DESCRIPTION

       Performs one of several network socket operations, providing a means to manipulate and use
       sockets directly within AOLserver.

       ns_sockaccept sockid

              Accepts a new connection on the socket specified  by  sockid  and  returns  a  list
              containing the read and write file descriptors for the socket, respectively.

              The  file  descriptors  can  be  used  with Tcl's puts, gets, read or any other Tcl
              socket manipulation commands.

              ns_sockaccept does not create a socket for you. It is normally used in  conjunction
              with ns_sockcallback, ns_socklisten, and ns_socklistencallback.

              You  can  use ns_sockcheck to see if the socket is valid before using ns_sockaccept
              on it.

       ns_sockblocking sockid

              Sets the socket specified  by  sockid  to  blocking  mode.  In  blocking  mode,  an
              operation  on  a socket must complete before the command can return. This can cause
              your process or thread to block forever if the operation does not complete. If that
              happens  in  an  ADP,  the page may never complete until the socket is interrupted,
              closed or a TCP timeout occurs.

       ns_sockcallback sockid script when

              Registers a socket callback script that will be run when a connection  is  made  to
              the socket specified by sockid.

              The socket must already exist. You can create a socket using ns_socklisten.

              The script should accept sockid and when as its first two arguments.

              The  script  is  responsible  for doing an ns_sockaccept on sockid prior to reading
              from and writing to the socket.

              If the same script will handle all when values, you must still register the  script
              four separate times, once for each type of when value.

              The  when  value is passed to script when script is invoked.  The when value is one
              of:

                 r - the socket is readable

                 w - the socket is writeable

                 e - the socket has an exceptional condition

                 x - the server is shutting down

       ns_sockcheck fileid

                 Uses recv() or send() calls to check if a socket is still connected. The  fileid
                 is the read or write file id returned by ns_sockopen.

                 This  function is useful if you used the -nonblock option with ns_sockopen after
                 calling ns_sockselect.

       ns_socketpair
                 Creates a pair of connected sockets and returns a list of file  ids:  the  first
                 one for reads and the second one for writes.

       ns_socklisten address port
                 Creates  a  new  socket and listens for connections at the specified address and
                 port. An asterisk (*) can be  used  as  the  address  argument  to  specify  all
                 addresses.

                 The socket id is returned.

                 You must use ns_sockaccept to accept connections on the socket.

       ns_socklistencallback address port script

                 Creates  a  new  socket and listens for connections at the specified address and
                 port. An asterisk (*) can be  used  as  the  address  argument  to  specify  all
                 addresses.

                 Runs script when a new connection is received. The script must use ns_sockaccept
                 on the

       ns_socknonblocking sockid

                 Sets the socket specified by sockid to nonblocking.

       ns_socknread sockid

                 Returns the number of bytes waiting to be read  from  the  socket  specified  by
                 sockid.

       ns_sockopen ?-nonblock | -timeout seconds? host port

                 Uses  the  socket(), bind() and connect() calls to connect to the remote host on
                 the specified port. ns_sockopen returns a list containing  the  read  and  write
                 fileids, respectively.

                 The -nonblock option causes ns_sockopen to return immediately, while the connect
                 is still in progress by the operating system. Use ns_sockcheck  with  the  write
                 fileid  to  see  if  the connect has completed before attempting to read from or
                 write to the socket.

                 The -timeout option specifies how long to wait for the connect  to  be  made  in
                 seconds before timing out.

       ns_sockselect ?-timeout seconds? rfds wfds efds

                 Uses  a  call  to  select() to determine which fileids are readable, writable or
                 have exceptional conditions.  ns_sockselect  returns  a  list  of  three  lists:
                 readable fileids, writable fileids, and the fileids with exceptions.

                 The  -timeout option specifies how many seconds to wait for ns_sockselect before
                 timing out.

                 The rfds, wfds and efds arguments  are  lists  of  readable  fileids,  writeable
                 fileids, and fileids with exceptions, respectively.

       Be  careful  using  these  socket commands in an ADP or a procedure called by an ADP. If a
       socket command hangs, the page may not finish being served  to  the  user  until  the  TCP
       connection times out, typically several minutes later.

SEE ALSO

       nsd(1), info(n)

KEYWORDS