23. Socket Programming

J provides the standard set of socket functions. This chapter assumes you already understand socket programming and provides a description of J's facilities.

First, you must load the script that defines the socket interface: require 'socket'

(require is like load but if the file has already been loaded it does nothing). This will define a number of variables inside J. You must make the variables visible to your program, and the easiest way to do that is with the verb DefSockets defined in system\packages\misc\jforc.ijs:

DefSockets ''

You are then ready to create a socket: sdsocket AF_INET,SOCK_STREAM,0

+-+--+ |0|96| +-+--+

sdsocket returns return_code;socket_number . Nonzero return codes indicate errors; look in J_directory/system/main/socket.ijs for definitions. The valid address families and socket types are defined in

J_directory/system/main/defs/netdefs_YourOS.ijs.

sdselect

You check the status of sockets with

sdselect read_list;write_list;error_list;maxtime

The three lists are lists of sockets and maxtime is a time in milliseconds. sdselect will delay for a maximum of maxtime milliseconds until it sees a socket in read_list that is ready for reading, or one in write_list that is ready for writing, or one in error_list that has an error. When it finds a qualifying socket, or when the time limit is reached, it returns result_code;read_ready_list;write_ready_list;error_list which lists all the qualifying sockets. A maxtime of 0 always returns immediately, giving the current status of the specified sockets.

If sdselect is invoked with an empty operand (sdselect ''), it checks all sockets with a maxtime of 0.

Asynchronous Sockets and socket_handler

By default, sockets created by sdsocket are blocking sockets; an operation on such a socket waits until data is available. This can tie up your J session while the remote computer is responding, so if you are serious about your socket programming you will want to make your sockets nonblocking. You do so with

138

sdasync socket_number

which marks that socket as nonblocking and requests notification of changes in its status. All operations to a nonblocking socket return immediately (with the error code EWOULDBLOCK if the operation cannot be immediately completed). When there is a change in the status of a nonblocking socket, the interpreter executes

socket_handler ''

and it is up to you to have a socket_handler defined that will use sdselect to see what sockets are ready for transfers and then execute those transfers.

Names and IP Addresses

Sockets are addressed by IP address and port number. To translate a domain name to an IP address, use

sdgethostbyname domain_name for example,

sdgethostbyname 'www.jsoftware.com' +-+-+---------------+ |0|2|216.122.139.159| +-+-+---------------+

where the result is return_code;address_family;address . If the domain is unknown an address of '255.255.255.255' is returned.

sdgethostbyaddr address_family;address will translate an IP address back to a domain name.

The name of your machine is given by sdgethostname ''

+-+-----+ |0|1qfe3| +-+-----+

(result is return_code;name) so you can get your own IP address by sdgethostbyname 1 {:: sdgethostname ''

+-+-+-----------+ |0|2|65.80.203.8| +-+-+-----------+

If you have a socket with an active connection you can get some information about the machine on the other end with

where the result is return_code;address_family;remote_IP_addr;remote_port .

You can get information about your own end of a connected socket with

139

sdgetsockname socket_number +-+-+-----------+----+ |0|2|65.80.203.8|2982|

return_code;address_family;local_IP_addr;local_port .

Connecting

Reading from a Web site, you use the sequence sdsocket/sdconnect/sdsend/sdrecv/sdclose .

sdconnect socket;address_family;IP_addr;port will connect your socket to the remote machine addressed by

address_family;IP_addr;port . If the socket is blocking, sdconnect completes when the connection has been made. If the socket is nonblocking, sdconnect will return immediately with the error code EWOULDBLOCK and socket_handler will be called when the connection has been made. An example is

sdconnect 184;2;'64.58.76.229';80

With the connection established, you can send data with data sdsend socket;flags

where the flags are any of the MSG_ values from socket.ijs, usually 0. The result is return_code;number_of_bytes_sent . Fewer bytes may be sent than were in your data; you will have to resend the excess.

You receive data with

sdrecv socket,count,flags

where count is the maximum number of bytes you will accept and flags are any of the MSG_ values from socket.ijs, usually 0. The result is return_code;data . If the socket is blocking, sdrecv will wait until it is ready for reading; if the socket is nonblocking, sdrecv will immediately return (presumably you issued the sdrecv only after using sdselect to verify that the socket was ready for reading). In either case, sdrecv will return with data if it has any; if the length of

data is 0, that means that the connection was closed by the peer and all data sent by the peer has been received.

When you have finished all you data transfers for a socket, ,you must close it with sdclose socket

which has as result an unboxed return_code .

Listening

If you want to wait for a remote machine to get in touch with you, use the sdbind/sdlisten/sdaccept sequence instead of sdconnect . The sequence is:

sdbind socket;address_family;IP_addr;port

to establish a connection between the socket and the address given by address_family;IP_addr;port . If IP_addr is '', the socket can be used to

140

listen for a connection to any address on the machine. If port is 0, the system will assign a port number. The result of sdbind is an unboxed return_code .

sdlisten socket;connection_limit

causes the operating system to start listening for connections to the address bound to socket . The result is an unboxed return_code .A maximum of connection_limit connections can be queued awaiting sdaccept . When a connection is made to a listening socket's address, the socket is shown in sdselect as ready to read, and you should issue

sdaccept socket

which will return return_code;clone_socket where clone_socket is a new socket, with all the attributes of socket but additionally with a connection to the remote host. You should direct all your sdsend, sdrecv, and sdclose operations to the clone_socket .

Other Socket Verbs

Datagrams

The sequences given above apply to sockets of type SOCK_STREAM, e. g. TCP sockets. Connectionless sockets with type SOCK_DGRAM are also supported, and could be used for UDP transfers. The verbs to use to transfer datagrams are

sdrecvfrom socket;count;flags

where count is the maximum number of bytes you will accept and flags are any of the MSG_ values from socket.ijs, usually 0. The result is return_code;data;sending_address . If the socket is blocking, sdrecvfrom will wait until it is ready for reading; if the socket is nonblocking, sdrecvfrom will immediately return (presumably you issued the sdrecvfrom only after using sdselect to verify that the socket was ready for reading). The returned data is the datagram, which may have a length of 0.

data sdsendto socket;flags;address_family;IP_addr;port where the flags are any of the MSG_ values from socket.ijs, usually 0. The datagram is sent to the remote address given by address_family;IP_addr;port, and the result is return_code;number_of_bytes_sent .

Socket Options

Verbs to query and set socket options are

sdgetsockopt socket;option_level;option_name with result return_code;option_value . Examples:

sdgetsockopt sk;SOL_SOCKET;SO_DEBUG sdgetsockopt sk;SOL_SOCKET;SO_LINGER

sdsetsockopt socket,option_level,option_name,value_list

(note that the operand is an unboxed list) The option is set, and the result is return_code;option_value . Examples:

141

sdsetsockopt sk,SOL_SOCKET,SO_DEBUG,1 sdsetsockopt sk,SOL_SOCKET,SO_LINGER,1 66

sdioctl socket,option,value

reads or sets control information (result is return_code;value). Examples: sdioctl sk,FIONBIO,0 NB. set blocking

sdioctl sk,FIONBIO,1 NB. set non-blocking sdioctl sk,FIONREAD,0 NB. count ready data

Housekeeping

sdgetsockets ''

The result is return_code;list_of_all_active_socket_numbers . sdcleanup ''

All sockets are closed and the socket system is reinitialized. The result is 0 .

142