ns_sock(3aolserver)					    AOLserver Built-In Commands 				       ns_sock(3aolserver)

__________________________________________________________________________________________________________________________________________________

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_sock-
	      listencallback.

	      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_sock-
		 open.

		 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

AOLserver								4.0						       ns_sock(3aolserver)