SYNOPSIS

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.

KEYWORDS