make-socket

Function

Package: socket

Arguments: &rest args&key type format connect address-family eol

Create and returns a socket object with characteristics specified by the arguments. make-socket checks whether multiprocessing has been started and starts it if it hasn't been. The socket object will be an instance of a particular class (see socket for a list of classes). The class is determined from the values supplied to the keyword arguments.

The keywords arguments have the following possible values (with the default value given first):

type	`:stream` or `:datagram`
format	All sockets are `:multivalent`. This argument is ignored.
address-family	`:internet` or `:file`
connect	`:active` or `:passive`
eol	kept for backward compatibility only (this argument was used in a much earlier release on WIndows). It should not be specified in new code.

All of the various kinds of sockets are created with make-socket, which determines the kind of socket you want based on the values of the type, format, connect, and address-family arguments. The value of the address-family keyword can't be :file on Windows because Windows does not support it.

make-socket calls a specialized socket creation function and that function looks for other keywords designed just for that socket type. We describe next the extra keywords that are permitted for given values of address-family and type

:address-family :internet :type :stream

These additional keyword arguments are valid: :local-port, :local-host, :remote-host, :remote-port, :backlog, :reuse-address, :broadcast:keepalive and :nodelay.

The port values are 16-bit integer or strings naming ports found in the operating system's services file and labeled as being "tcp" services. On Unix the file is called /etc/services. On Windows, it is in the Windows directory and is called services.

:local-host is usually only specified for :passive sockets. When specified it must be a host name or IP address belonging to one of the network interfaces on the machine on which Lisp is running. By specifying the :local-host you can select the network device on which the socket is made. For example if you specify the "127.1" then it restricts this socket to be on the loopback network which means that this socket can only connect to other sockets on the same machine. If :local-host isn't specified then the operation system will create the socket on the most appropriate network device when a connection is made to it.

The host value can be a 32-bit internet address or a string naming a host.

If the :local-port argument is not given, one will be selected by the system. You can use the local-port function to determine which port the system selected.

Note: The remote-host and remote-port values aren't used for :passive sockets.

The :backlog value is used by :passive sockets to tell the operating system how many connections can be pending (connected but for which an accept-connection hasn't been done). The default is 5.
:reuse-address sets the SO_REUSEADDR flag. This allows a particular port to be reopened in :connect:passive mode even if there is an existing connection for the port. This is very useful when debugging a server program since without it you may have to wait up to a minute after closing a particular port to reopen the same port again (due to certain port-non-reuse requirements found in the TCP/IP protocol).
:broadcast requests permission to send broadcast packets from this socket. Whether permission is granted depends on the policy of the operating system.
:keepalive if true then continue to verify that the the connection is alive by sending empty packets to the receiving end.
A passive internet address family socket can now be created with a specific :local-host value. Normally the :local-host doesn't need to be specified as the operating system will determine that when a connection is made. There may be times when you want to specify the local-host. For example, a convention has been established that every machine running tcp/ip has at least two IP addresses: one is associated with the ethernet card and one is for a local-to-the-machine network called the loopback network. The loopback IP address is usually 127.1 (it's a Class A address so it is written as two numbers). If you open up a passive socket and specify "127.1" as the local-host, then that means that only programs on your machine can connect to that socket. Naturally, this could very important for security reasons.
The :nodelay additional keyword argument: normally the network layer will delay sending small packets of data across the network, hoping that if it waits a bit longer there will be more data it can include in the packet. By passing a true value for the :nodelay argument you can turn off this optimization in the network layer.

:address-family :file :type :stream

These additional keyword arguments are valid: :local-filename, :remote-filename, and :backlog.
These are the files that name the local and remote filenames for the connection.
For :passive sockets the :local-filename must be specified (and :remote-filename will be ignored). For :active sockets :local-filename can be omitted but :remote-filename must be specified.
The filename specified must not already exist in the filesystem (or you'll get an error).

:address-family :internet :type :datagram

These additional keyword arguments are valid: :local-port, :local-host, :remote-host, and :remote-port, :reuse-address, :broadcast.
See the :internet :stream case above for the general meaning of the keywords. :reuse-address and :broadcast have the same meaning here are described there.
:local-host may be specified to select the network device on which the datagram socket is created. Specifying "127.1" for example will put the datagram socket on the loopback network and it will only receive datagrams from other processes on the same machine. If :local-host is not specified then the datagram socket will be on all network devices simultaneously.
A datagram socket is never connected to a remote socket, it can send a message to a different host and port each time data is sent through it. However if you know that you'll be sending data to a particular host and port with this socket, then you can specify that :remote-host and :remote-port when you create the socket. If you've done that then you can omit the :remote-host and :remote-port arguments to the send-to function. In other words, specifying the :remote-host and :remote-port just sets the default values for the :remote-host and :remote-port arguments when a send-to is done.

:address-family :file :type :datagram

These additional keyword arguments are valid: :local-filename and :remote-filename.
See the :file :stream case above for the meaning of the keywords. As in the description just above, if you specify a :remote-filename then you are merely setting the default value for the :remote-filename argument when a send-to is done.

See socket.htm for general information on sockets in Allegro CL.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.