make-socket

Arguments: &rest args &key type format connect address-family eol ipv6 scope-id tcp-md5-sig-key tcp-md5-sig-key-ef

Create and return 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):

Further notes on the :ipv6 keyword argument

If remote-host and/or local-host are specified as hostname strings, they will be resolved by calling lookup-hostname. make-socket's ipv6 keyword argument will be passed through to lookup-hostname (which is also modified to accept IPv6 addresses).

make-socket does not allow the creation of an IPv6 socket with an IPv4 remote host. The success or failure of creating an IPv4 socket with an IPv6 remote host is operating system dependent.

Some operating systems allow the creation on an IPv6 passive socket which will accept both IPv4 and IPv6 connections. Others (typically for security reasons) require separate passive sockets for IPv4 and IPv6. Consult your operating system documentation for details.

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.

The following socket options for an existing socket can be modified with set-socket-options. The options that can be set are reuse-address, broadcast, keepalive, nodelay, oob-inline, receive-buffer-size, and send-buffer-size. Not all options are relevant for all types of sockets. Look at the man pages for your specific OS to see what options are supported for particular sockets. Each socket type below specifies additional keyword arguments accepted by make-socket.

Additional options are tcp-keepalive-idle-time, tcp-keepalive-probe-interval, and tcp-keepalive-max-probes. These correspond to the C constants TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT available on some (but not all) operating systems. These can only be set with set-socket-options. See the description of that function for more information.

make-socket calls a specialized socket creation function and that function looks for other keywords designed just for that socket type (some naming options that can be modified with set-socket-options). 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, :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 also called services but is located in different places in different versions, such as C:\WINNT\system32\drivers\etc\ in Windows 2000 and C:\XPPRO\system32\drivers\etc\ in Windows XP.

: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 operating 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, a string naming a host, or an IPv6 address.

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).

:keepalive if true then continue to verify that 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 be 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. A true value for the :nodelay argument (which, starting in release 6.2, is the default) suppresses that optimization in the network layer. Specifying nil as the value allows the delay optimization, but is rarely beneficial unless the network is very slow.

: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 has the same meaning here as 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.

:broadcast requests permission to send broadcast packets from this socket. Whether permission is granted depends on the policy of the operating system. To send a broadcast packet you must specify the broadcast IP address for the network on which you want to broadcast. The convention is that the broadcast address is the highest numbered host address on a network. For example, if the machine has a network interface with an IP address of 192.168.1 34 then it is on network 192.168.1.0 and the broadcast address for that network will mostly likely be 192.168.1.255.

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.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.