make-socket

Function

Package: ACL-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 keywords arguments have the following possible values (with the default value given first):

type	:stream or :datagram
format	:text or :binary and, for :stream sockets only, :bivalent
address-family	:internet or :file
connect	:active or :passive

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, :remote-host , :remote-port, :backlog, :reuse-address, :broadcast and :keepalive.

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.

The host value can be a 32-bit internet address or a string naming a host. Currently it cannot be a string with a dotted IP address, e.g. "192.132.95.1".

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 this 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. [Currently this is not implemented for datagram sockets which is the only place it makes sense.]

:keepalive if non-nil 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.

: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, :remote-host, and :remote-port.

See the :internet :stream case above for the meaning of the keywords. 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.

The general documentation description is in introduction.htm. The index in index.htm.