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