Function | Package: socket | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 The object described on this page has been modified in the 10.1 release; see the Release Notes. 10.0 version

## 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):

type | `:stream` or `:datagram`
format | All sockets are `:multivalent`. This argument is ignored.
address-family | `:internet` or `:file`
connect | `:active` or `:passive`
ipv6 | The default is the value of `*ipv6*`. If `nil`, then an IPv4 socket will be created (unless local-host or remote-host are specified as an IPv6 address). If non-`nil`, then an IPv6 socket will be created. See the note below for additional information. (If an IPv6 socket is requested but the underlying operating system does not have IPv6 support enabled, an error will be signaled.)
scope-id | this argument specifies the interface to use when making an IPv6 connection to remote-host. If remote-host is specified and is an ipv6-address structure, its scope-id slot will be updated to the value of the scope-id keyword argument. If scope-id is not specified, then the scope-id slot of the remote-host argument will be used. If remote-host is not specified or does not have a scope-id, then 0 will be used.
tcp-md5-sig-key | If tcp-md5-sig-key is non-`nil`, it must be a string or octet array which will be used to set the TCP MD5 signature key to be used during the connection to remote-host. If tcp-md5-sig-key is a string, tcp-md5-sig-key-ef can be supplied to specify a non-default external format for the string. The string will not be null-terminated. This argument and tcp-md5-sig-key-ef are accepted on any platform but have effect only on Linux platforms. They are only relevant for active IPv4/IPv6 connections. See set-tcp-md5-sig.
tcp-md5-sig-key-ef | If tcp-md5-sig-key is a string, tcp-md5-sig-key-ef can be supplied to specify a non-default external format for the string. The string will not be null-terminated. This argument and tcp-md5-sig-key are accepted on any platform but have effect only on Linux platforms. They are only relevant for active ipv4 connections. See set-tcp-md5-sig.
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.

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

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 The object described on this page has been modified in the 10.1 release; see the Release Notes. 10.0 version