|
Allegro CL version 11.0 | ||||||||
Generic function, acl-socket package
Arguments: sock &key (wait t)
If wait is true, waits for there to be a connection to this socket and returns a new stream object that can be used to do I/O to the connected socket. If wait is nil and there is no connection pending it returns nil immediately; if a connection is pending, connects and returns a new stream object that can be used to do I/O to the connected socket.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: &key nameserver search domain auto
In order to work, the DNS utility needs to know the IP address of at least one nameserver willing to respond to recursive queries (that is, to do the work of the query if it doesn't know the answer). This function is used to specify the nameserver addresses. It can also specify other optional information. When DNS is configured, the variable *dns-configured* is set to true.
The arguments:
We would like to be able to compute this information automatically in every situation. Currently we can handle Unix machines that specify this information in a file called
When dns-query is called, it checks to see if configure-dns has been called since lisp started, and if not it calls configure-dns with :auto t. If this doesn't work it means that you need to call configure-dns with the appropriate information before you call dns-query on this machine.
On Windows the information we need to automatically configure this module is found in the Windows registry. Unfortunately the information we need is in a different place in each on the various Windows configurations we tested (such as Win NT 4 and Win2000, each with a fixed IP address or using DCHP to configure the IP address). Therefore it's likely that information will move around again in future versions of Windows. Furthermore sometimes we encounter stale information in the registry (for example, a laptop computer that used to be on a network but isn't at the moment may hold the last known nameserver information in the registry even though those nameservers are unreachable). Therefore, if you wish to make use of the Allegro CL DNS facility, you should be prepared to manually configure-dns on machines (by calling this function with auto nil and filling in the necessary information) when auto configuration fails.
See dns.html for information on the domain naming system utility in Allegro CL and see socket.html for general information on sockets in Allegro CL.
Arguments: name &rest rest
Function, acl-socket package
This function calls dns-query passing a type value of :ptr. This is the functional equivalent of ipaddr-to-hostname when you ignore the extra values returned.
See also *dns-mode*.
See dns.html for information on the domain naming system utility in Allegro CL and see socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: name &rest rest
This function calls dns-query passing a type value of :a. This is the functional equivalent of lookup-hostname if you ignore the extra values returned. It has one additional feature, which is that if the query on name doesn't return any IP addresses, and if name doesn't contain any periods (that is, it's not a fully qualified domain name), then we try appending the values in *domain-search-list* to the name and redoing the query. Because the query can be done once for the given name and once for each name in the *domain-search-list*, this function can take longer to return than dns-query when nameservers aren't responsive.
This function does not check a local file (often /etc/hosts) for name to IP address mappings. Thus there are cases where dns-lookup-hostname won't act just like lookup-hostname.
If a nameserver response is too large to fit in 512 bytes and is thus truncated, this function does not switch from UDP to TCP and retry the query.
See also *dns-mode*.
See dns.html for information on the domain naming system utility in Allegro CL and see socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: dns-nameserver-object
Accessor for the ipaddr slot of dns-nameserver-object. See dns-nameserver.
See dns.html.
Function, acl-socket package
Arguments: dns-nameserver-object
Accessor for the name slot of dns-nameserver-object. See dns-nameserver.
See dns.html.
Arguments: dns-nameserver-object
Accessor for the received slot of dns-nameserver-object. See dns-nameserver.
See dns.html.
Function, acl-socket package
Arguments: dns-nameserver-object
Accessor for the sent slot of dns-nameserver-object. See dns-nameserver.
See dns.html.
Function, acl-socket package
Arguments: name &key type nameserver repeat timeout queue decode search ignore-cache
The arguments are:
| Name | Default | What |
|---|---|---|
| name | Depending on the value of the type argument, this is either a string or an integer IP address. | |
| type | :a |
The type of dns query to make.:a means determine
the ip address(es) for the given name. (name
should be a string.):ptr means determine the
hostname for a given IP address.
(name
should be an integer IP address, a string containing a
dotted IP address, or an IPv6 address.
:mx means determine if there is
another machine that email for name
should be directed. (name
should be a string.)
|
| nameserver | nil |
If specified this can be an IP address or a list of IP addresses. This overrides the configured list of nameservers for just this query. |
| repeat | 5 | How many times to try to get an answer to this query before giving up. |
| timeout | 5 | How long to wait until we assume that a try has failed and we then try again or give up. The value should be an integer indicating a number of seconds. |
| queue | t |
If true then handle this request using the
background process that is
backed up by a cache of recent answers.
If this is nil then a
request will always be sent to the nameserver |
| decode | t |
The nameserver returns a structure of many fields.
If true then dns-query
will examine the returned structures and will return only the
information requested by the
query.
If this is nil then the result of
dns-query will
be the actual information returned by the nameserver.
This response is a
dns-response object. See that
page for information on this raw object. Please specify
nil when you specify :any
as the value of type. |
| search | nil |
When specified true, *dns-domain* and *domain-search-list* will be used to fully qualify the name argument before doing the query. See below for details on how the search is conducted. |
| ignore-cache |
nil
|
Allegro CL DNS caches positive and negative responses for at least the time-to-live specified in the respones. If dns-query is called again with the same request before the time-to-live expires, the cached information will be returned immediately. If ignore-cache is true, then the cached value will be ignored and a DNS lookup will occur. |
If either nameserver is non-nil or decode is nil, then queue will be set to nil regardless of the value of queue supplied. This ensures that a fresh query is sent to the nameserver.
Where an IP address is a valid argument, it can be specified as either an integer or as a string such as "192.132.95.1" or "127.1". Ipv6 address structures and IPv6 colon hex strings are allowed too.
When the search keyword argument is specified true, and so *dns-domain* and *domain-search-list* are used to fully qualify the name argument before doing the query, the search steps are as follows:
The search list comprises *dns-domain* followed by *domain-search-list*. If the given name ends in a period (e.g. www.cnn.com.) then that is an absolute name. Only that name is checked and the search list is not used.
If the given name has a period in it, but that period is not at the end (e.g. www.cnn.com) then that name is checked first.
Finally for the given name N and for each name S in the search list a new name is constructed by concatenating the strings with a period in between (e.g N.S). That constructed name is used in the query. If the query returns a response with :no-such-domain then the next item in the search list is used.
Thus the first response from the search (with a positive or negative valid time, which is the second returned value) is returned as the first returned value, but illegal domains in the search list are ignored.
There are four return values from dns-query.
the primary answer
the amount of time that that answer is valid (in seconds) This can be a negative number (see the discussion in the The DNS API section of dns.html for why).
a list of other answers
a list of the flags returned by the dns server that replied to the query
There are examples of using dns-query in the subsections of The DNS API in dns.html.
See dns.html for information on the domain naming system utility in Allegro CL and see socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: dns-response-object
Accessor for the additional slot of dns-response-object. See dns-response.
See dns.html.
Function, acl-socket package
Arguments: dns-response-object
Accessor for the answer slot of dns-response-object. See dns-response.
See dns.html.
Function, acl-socket package
Arguments: dns-response-object
Accessor for the authority slot of dns-response-object. See dns-response.
See dns.html.
Function, acl-socket package
Arguments: dns-response-object
Accessor for the flags slot of dns-response-object. See dns-response.
See dns.html.
Function, acl-socket package
Arguments: dns-response-object
Accessor for the flags-value slot of dns-response-object. See dns-response.
See dns.html.
Function, acl-socket package
Arguments: dns-response-object
Accessor for the id slot of dns-response-object. See dns-response.
See dns.html.
Function, acl-socket package
Arguments: dns-rr-object
Accessor for the answer slot of dns-rr-object. See dns-rr.
See dns.html.
Function, acl-socket package
Arguments: dns-rr-object
Accessor for the class slot of dns-rr-object. See dns-rr.
See dns.html.
Function, acl-socket package
Arguments: dns-rr-object
Accessor for the name slot of dns-rr-object. See dns-rr.
See dns.html.
Function, acl-socket package
Arguments: dns-rr-object
Accessor for the time-to-live slot of dns-rr-object. See dns-rr.
See dns.html.
Function, acl-socket package
Arguments: dns-rr-object
Accessor for the type slot of dns-rr-object. See dns-rr.
See dns.html.
Function, acl-socket package
Arguments: object
This function was added in an update released around June 20, 2006.
Returns true if the argument is a string in dotted IP address form.
See socket.html, particularly the Host naming section, where the dotted form is described with examples.
Function, acl-socket package
Arguments: dotted &key errorp
If dotted is a string like "192.132.95.84" (or one of the extensions to this format), this function converts the string to an unsigned 32-bit IP address. If there are any invalid characters in the string then an error will be signaled unless the value of errorp keyword is nil, in which case nil is returned.
dotted-to-ipaddr supports IPv6 "colon hex" address notation, including the %scopeid extension. The scope id can be an interface number or interface name. dotted-to-ipaddr supports IPv4-mapped IPv6 address notation (::ffff:w.x.y.z).
"2001:5c0:0:2::24" ;; 6bone.net
"fe80::209:5bff:fe8e:61c1" ;; a link-local address
"fe80::209:5bff:fe8e:61c1%eth0" ;; a link-local address with scope-id
"fe80::209:5bff:fe8e:61c1%2" ;; a link-local address with numeric scope-id
"::" ;; unspecific/wildcard address
"::1" ;; loopback
"::ffff:192.168.0.1" ;; IPv4-mapped IPv6 addressSee also get-ip-interfaces.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: from-host from-port from-file (from-user "anonymous") (from-password "[email protected]") to-host to-port to-file (to-user "anonymous") (to-password "[email protected]") (mode :binary) debug*
This function transfers the file from-file from from-port on the from-host machine to to-file via the to-port on the to-host machine. (from-port and to-port have standard defaults and it is typical not to provide values for them. The arguments are there to allow specification of servers on non-default ports.) The files on the different machines can have different names. Users and passwords should be strings.
mode can be :binary (the default), or :text. :text mode lines end with cr-lf (the internet standard).
If debug is a stream (or t) is given, this function will print the ftp interaction to that stream.
Function, acl-socket package
Arguments:
This function returns a list of conses. The car of each cons is the interface id. The cdr of each cons is the name of the interface.
Either the numeric interface id or the name can be used in the %scopid extension of dotted (colon hex) IPv6 addresses.
This function is not supported on HP/UX. It also does not work (it typically signals an error when called) on Mac OS X 64-bit. (The problem on the Mac 64-bit seems to result from an Operating System bug, so it may at some later time be fixed by an OS update. This function does work on Mac OS X 32-bit.)
See also: dotted-to-ipaddr
See socket.html.
Generic Function, acl-socket package
Arguments: stream
get-ssl-peer-certificate returns an x509-certificate object representing the certificate that the peer supplied. If the peer did not supply a certificate, nil is returned. The x509-certificate is created the first time this function is called on a stream.
stream must be an SSL client or server stream (such as is created by make-ssl-server-stream and make-ssl-client-stream).
Note that get-ssl-peer-certificate automatically calls ssl-do-handshake if SSL handshake has not already occurred.
See socket.html.
Generic Function, acl-socket package
Arguments: stream
get-ssl-verify-result returns information about the success or failure of peer certificate verification.
stream must be an SSL client or server stream (such as is created by make-ssl-server-stream and make-ssl-client-stream).
get-ssl-verify-result returns two values. The first value is a numeric code indicating the status of verification. 0 indicates successful verification. The second value is a string with a text representation of the status.
Note, if SSL handshake has not yet been performed, or if the peer did not provide a certificate, this function returns an OK status.
The possible return values are shown in the following information copied from the OpenSSL documentation. The numeric value (0, 2, 3, 4, etc.) is the first returned value and the string is the second. The string does not include the capitalized and underscored descriptor. Additional information not included in the returned string is included in this list. Thus, when the peer certificate verification is sucessful, 0 and "ok" are returned. X509_V_OK and 'the operation was successful.' are not part of the string.
See socket.html.
Function, acl-socket package
Arguments: &key menup
On Unix systems this is unnecessary and always does nothing. On Windows, if the socket system has already been initialized then this does nothing. If it hasn't, then the socket system is initialized. If, on Windows, this function hasn't been called before the first network operation, then it will be called automatically.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: addr1 addr2 &key compare-scope-id
addr1 and addr2 should be ip addresses in some form (either dotted, 32-bit unsigned, or ipv6-address structure). This function returns true when the addresses match.
When comparing IPv6 addresses, normally the scope id is not used in the comparison. To include the scope id in the comparison, specify a non-nil value for the compare-scope-id keyword argument.
See socket.html.
Function, acl-socket package
Arguments: addr &key values
Convert a 32-bit unsigned IP address, ipaddr, to a string in dotted form. The value is always converted to the format "a.b.c.d", even if it is a class A or B address. If values is true, then return a, b, c and d as multiple values instead of a single string.
This function works on IPv6 address structures as well. If the IPv6 address structure's scope-id field is non-zero, then the dotted result will have the %scopeid extension. When an IPv6 address is specified, then the values keyword argument has no effect.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: ipaddr &key ignore-cache
ipaddr should be a 32-bit unsigned integer (representing an IPv4 address), an ipv6-address stucture, or a dotted IP address string. This function returns, as a string, the hostname of the machine with the given address.
if the ignore-cache argument is specified true, then the lookup will be done by querying the operating system ipaddr lookup libraries rather than using a value that Lisp has cached. The result of the lookup is still cached, however.
See also *dns-mode*.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: object
Returns true if the argument is an IP address (either an integer or an ipv6-address structure).
See socket.html.
Generic Function, acl-socket package
Arguments: internet-socket
Returns true if the argument, which must be an internet socket, is a IPv6 socket. See make-socket.
See socket.html.
Function, acl-socket package
Arguments: object
Returns true if the argument is an IPv6 address structure.
See socket.html.
Generic Function, acl-socket package
Arguments: af-file
Returns the local filename of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: af-internet
Returns an IP address. You can use ipaddr-to-dotted or ipaddr-to-hostname to make a more readable version of this value if you plan to print it out.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: af-internet
Returns the local port of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: host &key ignore-cache ipv6 all
host should be a string naming a host, a 32-bit IP address, a string in dotted form, or an IPv6 address. This function returns the 32-bit IP address or an IPv6 address structure for the host. An error is signaled if the host can not be found. See the documentation for *dns-mode* for information on the manner in which name resolution occurs.
To enhance performance, lookup-hostname caches answers to queries and reuses those answers for subsequent lookups of the same name. If the IP address associated with a given hostname has changed since the information was cached, lookup-hostname may return out-of-date information.
If the ignore-cache argument is specified true, then the lookup will be done by querying the operating system libraries rather than using a value that Lisp has cached. The result of the lookup is still cached, however.
The ipv6 keyword argument was added with IPv6 support. ipv6 defaults to the value of *ipv6*. If nil, only IPv4 addresses will be returned. If :ipv6, then only IPv6 addresses will be returned. If t, then IPv6 addresses (if any) are returned in preference of IPv4 addresses. If ipv6 and all are both t, IPv6 addresses will be before IPv4 addresses in the returned list.
The all keyword argument was added with IPv6 support. If all is true, this function will return a list of all records.
See also *dns-mode*.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: port protocol
A port number is a 16-bit unsigned number (except port 0 is not used). Certain commonly used ports on machines are given symbolic names. The mapping between name and port number is kept in a file in the system area of the machine (often /etc on Unix and the Windows system directory on MS Windows). Given a symbolic name as the value of port and a protocol (either "tcp" or "udp"), lookup-port returns the associated port number (or signals an error if such a port doesn't exist). The reason that the protocol type is supplied is that the port N for protocol "tcp" is distinct from port N for protocol "udp".
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
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.html for general information on sockets.
Function, acl-socket package
Arguments: &key method certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file prefer-server-cipher-order
This function creates and returns an SSL context object (an instance of the class excl::ssl-context) suitable for use as the value of the context keyword argument to make-ssl-client-stream.
The context has values for all relevant arguments. For the arguments method, ciphers, ciphersuites, verify, max-depth, and prefer-server-cipher-order, specifying a value in a call to make-ssl-client-stream which is also passed a context object as the value of the context argument causes the associated argument value to be local to that connection (i.e. the specified argument value overrides the value in the context object). The value for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check cannot be overridden when a context is provided. It is an error to supply a context and values for any of those arguments.
method keyword argument values are described here. The list form discussed at the previous link is accepted by this function.
certificate: (default is nil) this argument names a file which contains one or more PEM-encoded certificates. The first (or only) certificate in the file will be used to identify the client (in the case of make-ssl-client-stream). Optionally, subsequent entries in the file may be used to supply intermediate CA certificates (also known as a certificate chain).
key: (default is nil) this argument is a string or pathname naming a file containing the private RSA key corresponding the the public key in the certificate. The file must be in PEM format. The key can be stored in an encrypted form which requires a pass phrase to read, but in that case the certificate-password must also be specified. If the key is stored in the certificate file, then you needn't specify the key argument.
certificate-password: (default is nil) this argument, if specified, should be a string. If the private key stored with the certificate inside the file named by the certificate argument is encrypted, then this value is used as the key to decrypt it.
verify: (default is :optional) this argument can be nil, :optional, or :required. Due to the way OpenSSL is implemented, the behavior of peer verification differs for servers and clients; here is the behavior for clients:
:verify nil means that no automatic verification will occur on the server-supplied certificate. Manual verification can be done using get-ssl-peer-certificate and get-ssl-verify-result.
:verify :optional means that the server's certificate (if supplied) will be automatically verified during SSL handshake. If verification fails, an error will be generated during SSL handshake. This is the default for client streams.
:verify :required means that the server's certificate will be automatically verified during SSL handshake. If the server does not supply a certificate or if verification of the supplied certificate fails, an error will be generated during SSL handshake.
maxdepth: (default is 10) the value must be an integer which indicates the maximum allowable depth of the certificate verification chain. If the chain exceeds this depth, an error will be generated during SSL handshake.
ca-file: (default is "sys:;examples;ssl;ca-bundle.crt") this argument specifies the name of a file containing a series of trusted PEM-encoded Intermediate CA or Root CA certificates that will be used during peer certificate verification. Keep in mind that, when using on an SSL server, the subject name information for each of these certificates is supplied to the peer during SSL handshake, so you may want to keep the number of certificates listed in the file to a minimum. A file containing certificates of well-known root CAs can be found in [acl directory]/examples/ssl/ca-bundle.crt, (to give the actual pathname, a logical pathname is used to specify the default value).
ca-directory: (default is nil) this argument specifies the name of a directory containing a series of trusted Intermediate CA or Root CA certificate files that will be used during peer certificate verification. Each file in the directory should contain one certificate. The files should be named based on the hash value of the certificate subject name. If more than one certificate with the same hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash (available via standard OpenSSL distributions) utility to create the necessary links.
ciphers: (default is the string given at the end of this paragraph) if the ciphers keyword argument is supplied, it must be a string which specifies an OpenSSL cipher list. This list determines which ciphers the SSL server will support. The strongest common entry from this list and the list supplied by the client during handshake will be used. If there is no entry in common, SSL handshake will fail and an error will be generated. This argument is not used with TLS 1.3. See the ciphersuites argument below. For details on the cipher list format, see https://www.openssl.org/docs/apps/ciphers.html. The default value is the string "ALL".
ciphersuites: used by TLS 1.3. See TLS 1.3 support and ciphersuites in socket.html for more information and suitable values. When nil or unspecified, OpenSSL defaults are used.
crl-check: (default is nil) this argument controls certificate revocation list (CRL) checking. Its value may be nil (the default) for no CRL checking, t for CRL checking of the peer's certificate (if provided by the peer), or :all for CRL checking of all components of the peer's supplied certificate chain. If this argument is non-nil, the verify argument must also be non-nil. If you enable CRL checking, you must supply a proper PEM-encoded CRL, even if it contains zero revocations. If you do not supply a CRL, peer verification will never succeed.
crl-file: (default is value of the ca-file argument) this argument specifies the location of a PEM-encoded CRL file. If nil or not supplied, defaults to the value of the ca-file argument. It is acceptable for CRL to be included amongst other PEM-encoded certificates.
prefer-server-cipher-order: this argument is ignored. (It is used by make-ssl-server-context and that function and this one have the same argument lists.)
See socket.html for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.
Function, acl-socket package
Arguments: socket &key context method certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file server-name
You must have the OpenSSL libraries installed for this facility to work. Note that shared library versions of the OpenSSL libraries (required by Allegro CL) are not available on all platforms. The SSL functionality is in the (require :ssl). Calling this function automatically loads the module.
This function creates and returns a new SSL server socket stream that communicates via SSL via the given socket. Once this function is called and an SSL socket stream is returned, no I/O calls should be done directly to socket. Note that closing the SSL socket stream will result in the original socket file descriptor being closed as well. Therefore, the idiomatic way to establish an SSL server socket stream is:
;; SOCK is already a socket:
(setf sock (make-ssl-server-stream sock ...))Unless ssl-do-handshake is called, the secure connection isn't negotiated until the first byte is sent through the SSL socket stream to the underlying stream (and this will usually occur when the first force-output is done to the SSL socket stream).
When that first write is done a negotiation process is begun that involves reads and writes. This negotiation process will not occur if the SSL socket on the other end of the connection is not sitting waiting for data to arrive. Thus if you create two connected sockets in a single Lisp process, and make one the client and the other the server, and then write to the client side the Lisp will hang since the server side socket isn't being read. You can make this work if you use the Lisp multiprocessing facility (see multiprocessing.html) to cause the server socket to be read at the same time that the write to the client socket is being done.
The context keyword argument takes an SSL context object as a value. Such objects contain relevant information about the client stream being created. The function make-ssl-client-context create a context suitable for a client stream.
Note: if you supply an SSL context object as the value of context, you can specify values for the arguments method, ciphers, ciphersuites, verify, and max-depth in the call to this function. Doing so causes the associated argument value to be local to the connection being created (i.e. the specified argument value overrides the value in the context object). However, it is an error to specify values for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check. Those arguments cannot be overridden when a context is provided.
If an error occurs, a condition of type excl::ssl-error is signaled. This condition has slots what (a string indicating what internal operation was being performed when the error occurred), codes (a ist of numeric OpenSSL error codes that represented the accumulated errors that resulted in the final error), strings (a list of the corresponding string forms of the OpenSSL error codes in the 'codes' slot) and verify-result, and verify-result-string. The last two will be populated if possible when an ssl error occurs. If non-nil, this information is included in the printed representation of the condition. This aids recognizing and debugging certificate-related SSL errors.
make-ssl-client-stream's keyword arguments are the same as make-ssl-server-stream's. The keyword arguments to make-ssl-client-stream are:
method keyword argument values are described here.
certificate names a file which contains one or more PEM-encoded certificates. The first (or only) certificate in the file will be used to identify the client (in the case of make-ssl-client-stream) or server (in the case of make-ssl-server-stream). Optionally, subsequent entries in the file may be used to supply intermediate CA certificates (also known as a certificate chain).
The key argument is a string or pathname naming a file containing the private RSA key corresponding the the public key in the certificate. The file must be in PEM format. The key can be stored in an encrypted form which requires a pass phrase to read, but in that case the certificate-password must also be specified. If the key is stored in the certificate file, then you needn't specify the key argument.
The certificate-password argument, if specified, should be a string. If the private key stored with the certificate inside the file named by the certificate argument is encrypted, then this value is used as the key to decrypt it.
verify can be nil (the default), :optional, or :required. Due to the way OpenSSL is implemented, the behavior of peer verification differs for clients and servers. Here we describe the behavior for clients. See make-ssl-server-stream for a discussion of the server behavior.
:verify nil means that no automatic verification will occur on the server-supplied certificate. Manual verification can be done using get-ssl-peer-certificate and get-ssl-verify-result.
:verify :optional means that the server's certificate (if supplied) will be automatically verified during SSL handshake. If verification fails, an error will be generated during SSL handshake.
:verify :required means that the server's certificate will be automatically verified during SSL handshake. If the server does not supply a certificate or if verification of the supplied certificate fails, an error will be generated during SSL handshake.
maxdepth must be an integer (which defaults to 10) which indicates the maximum allowable depth of the certificate verification chain. If the chain exceeds this depth, an error will be generated during SSL handshake.
ca-file specifies the name of a file containing a series of trusted PEM-encoded Intermediate CA or Root CA certificates that will be used during peer certificate verification. A file containing certificates of well-known root CAs can be found in [acl directory]/examples/ssl/ca-bundle.crt.
ca-directory specifies the name of a directory containing a series of trusted Intermediate CA or Root CA certificate files that will be used during peer certificate verification. Each file in the directory should contain one certificate. The files should be named based on the hash value of the certificate subject name. If more than one certificate with the same hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash utility (available via standard OpenSSL distributions) to create the necessary links.
ciphers: if the ciphers keyword argument is supplied, it must be a string which specifies an OpenSSL cipher list. The list is advertised to the SSL server during handshake. From that list, the SSL server will select a cipher to use for subsequent communications. If the SSL server does not support any of the ciphers in the list, SSL handshake will fail and an error will be generated.
For details on the cipher list format, see openssl.org.
This argument is support for TLS 1.3 and there may be cases when both ciphers and ciphersuites (see below) may be desirable in a call.
ciphersuites: used by TLS 1.3. See TLS 1.3 support and ciphersuites in socket.html for more information and suitable values. When nil or unspecified, OpenSSL defaults are used.
crl-check: this argument controls certificate revocation list (CRL) checking. Its value may be nil (the default) for no CRL checking, t for CRL checking of the peer's certificate (if provided by the peer), or :all for CRL checking of all components of the peer's supplied certificate chain. If this argument is non-nil, the verify argument must also be non-nil. If you enable CRL checking, you must supply a proper PEM-encoded CRL, even if it contains zero revocations. If you do not supply a CRL, peer verification will never succeed.
crl-file: this argument specifies the location of a PEM-encoded CRL file. If nil or not supplied, defaults to the value of the ca-file argument (if supplied). It is acceptable for CRL to be included amongst other PEM-encoded certificates.
server-name: This argument indicates which hostname the client is attempting to connect to. This information is passed to the server to allow it to select the SSL certificate to present to the client. The variable acl-socket:*ssl-features* has as its value a list of keywords indicating SSL supported features, such as :sni.
See make-ssl-server-stream. See also socket.html for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.
Function, acl-socket package
Arguments: &key method certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file (prefer-server-cipher-order t) server-name
This function creates and returns an SSL context object (an instance of the class excl::ssl-context) suitable for use as the value of the context keyword argument to make-ssl-server-stream.
The context has values for all relevant arguments. For the arguments method, ciphers, ciphersuites, verify, max-depth, and prefer-server-cipher-order, specifying a value in a call to make-ssl-server-stream which is also passed a context object as the value of the context argument causes the associated argument value to be local to that connection (i.e. the specified argument value overrides the value in the context object). The value for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check cannot be overridden when a context is provided. It is an error to supply a context and values for any of those arguments.
method keyword argument values are described here. The list form discussed at the previous link is accepted by this function.
certificate: (default is nil) this argument names a file which contains one or more PEM-encoded certificates. The first (or only) certificate in the file will be used to identify the client (in the case of make-ssl-client-stream). Optionally, subsequent entries in the file may be used to supply intermediate CA certificates (also known as a certificate chain).
key: (default is nil) this argument is a string or pathname naming a file containing the private RSA key corresponding the the public key in the certificate. The file must be in PEM format. The key can be stored in an encrypted form which requires a pass phrase to read, but in that case the certificate-password must also be specified. If the key is stored in the certificate file, then you needn't specify the key argument.
certificate-password: (default is nil) this argument, if specified, should be a string. If the private key stored with the certificate inside the file named by the certificate argument is encrypted, then this value is used as the key to decrypt it.
verify: (default is nil) this argument can be nil, :optional, or :required. Due to the way OpenSSL is implemented, the behavior of peer verification differs for servers and clients; here is the behavior for servers:
:verify nil means that the server will not ask the client to supply a certificate and will not do automatic verification if the client supplies a certificate anyway. If the client does provide a certificate, manual verification can be done using get-ssl-peer-certificate and get-ssl-verify-result.
:verify :optional means that the client will be asked to supply a certificate during SSL handshake. The certificate (if supplied) will be automatically verified during SSL handshake. If verification fails, an error will be generated during SSL handshake.
:verify :required means that the client will be asked to supply a certificate during SSL handshake. The client certificate will be automatically verified during SSL handshake. If the client does not supply a certificate or if verification of the supplied certificate fails, an error will be generated during SSL handshake.
maxdepth: (default is 10) the value must be an integer which indicates the maximum allowable depth of the certificate verification chain. If the chain exceeds this depth, an error will be generated during SSL handshake.
ca-file: (default is nil) this argument specifies the name of a file containing a series of trusted PEM-encoded Intermediate CA or Root CA certificates that will be used during peer certificate verification. Keep in mind that, when using on an SSL server, the subject name information for each of these certificates is supplied to the peer during SSL handshake, so you may want to keep the number of certificates listed in the file to a minimum. A file containing certificates of well-known root CAs can be found in [acl directory]/examples/ssl/ca-bundle.crt.
ca-directory: (default is nil) this argument specifies the name of a directory containing a series of trusted Intermediate CA or Root CA certificate files that will be used during peer certificate verification. Each file in the directory should contain one certificate. The files should be named based on the hash value of the certificate subject name. If more than one certificate with the same hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash (available via standard OpenSSL distributions) utility to create the necessary links.
ciphers: (default is the string given at the end of this paragraph) if the ciphers keyword argument is supplied, it must be a string which specifies an OpenSSL cipher list. This list determines which ciphers the SSL server will support. The strongest common entry from this list and the list supplied by the client during handshake will be used. If there is no entry in common, SSL handshake will fail and an error will be generated. For details see openssl.org. This argument is not used with TLS 1.3. See the ciphersuites argument below. The default value is the string "ALL".
ciphersuites: used by TLS 1.3. See TLS 1.3 support and ciphersuites in socket.html for more information and suitable values. When nil or unspecified, OpenSSL defaults are used.
crl-check: (default is nil) this argument controls certificate revocation list (CRL) checking. Its value may be nil (the default) for no CRL checking, t for CRL checking of the peer's certificate (if provided by the peer), or :all for CRL checking of all components of the peer's supplied certificate chain. If this argument is non-nil, the verify argument must also be non-nil. If you enable CRL checking, you must supply a proper PEM-encoded CRL, even if it contains zero revocations. If you do not supply a CRL, peer verification will never succeed.
crl-file: (default is value of the ca-file argument) this argument specifies the location of a PEM-encoded CRL file. If nil or not supplied, defaults to the value of the ca-file argument. It is acceptable for CRL to be included amongst other PEM-encoded certificates.
prefer-server-cipher-order: (default is t). The typical behavior when choosing a cipher during an SSLv3 or TLSv1 handshake is to use the client's preference. If this argument is true (the default), the server's preference will be used.
server-name: this argument appears in the argument list for this function but is not supported at this time. Do not specify a value for that argument.
See socket.html for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.
Function, acl-socket package
Arguments: socket &key context certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file prefer-server-cipher-order server-name
You must have the OpenSSL libraries installed for this facility to work. Note that shared library versions of the OpenSSL libraries (required by Allegro CL) are not available on all platforms. The SSL functionality is in the (require :ssl). Calling this function automatically loads the module.
This function creates and returns a new SSL server socket stream that communicates via SSL via the given socket. Once this function is called and an SSL socket stream is returned, no I/O calls should be done directly to socket. Note that closing the SSL socket stream will result in the original socket file descriptor being closed as well. Therefore, the idiomatic way to establish an SSL server socket stream is:
;; SOCK is already a socket:
(setf sock (make-ssl-server-stream sock ...))Unless ssl-do-handshake is called, the secure connection isn't negotiated until the first byte is sent through the SSL socket stream to the underlying stream (and this will usually occur when the first force-output is done to the SSL socket stream).
When that first write is done a negotiation process is begun that involves reads and writes. This negotiation process will not occur if the SSL socket on the other end of the connection is not sitting waiting for data to arrive. Thus if you create two connected sockets in a single Lisp process, and make one the client and the other the server, and then write to the client side the Lisp will hang since the server side socket isn't being read. You can make this work if you use the Lisp multiprocessing facility (see multiprocessing.html) to cause the server socket to be read at the same time that the write to the client socket is being done.
The context keyword argument takes an SSL context object as a value. Such objects contain relevant information about the server stream being created. The function make-ssl-server-context create a context suitable for a server stream.
Note that if you supply an SSL context object as the value of context, you can specify values for the arguments method, ciphers, ciphersuites, verify, max-depth, and prefer-server-cipher-order in the call to this function. Doing so causes the associated argument value to be local to the connection being created (i.e. the specified argument value overrides the value in the context object). However, it is an error to specify values for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check as they cannot be overridden when a context is provided.
The server-name keyword argument appears in the argument list for this function but is not supported at this time. Do not specify a value for that argument.
If an error occurs, a condition of type excl::ssl-error is signaled. This condition has slots what (a string indicating what internal operation was being performed when the error occurred), codes (a ist of numeric OpenSSL error codes that represented the accumulated errors that resulted in the final error), strings (a list of the corresponding string forms of the OpenSSL error codes in the 'codes' slot) and verify-result, and verify-result-string. The last two will be populated if possible when an ssl error occurs. If non-nil, this information is included in the printed representation of the condition. This aids recognizing and debugging certificate-related SSL errors.
make-ssl-server-stream's keyword arguments are the same as make-ssl-client-stream's. The keyword arguments to make-ssl-server-stream are:
method keyword argument values are described here.
certificate names a file which contains one or more PEM-encoded certificates. The first (or only) certificate in the file will be used to identify the client (in the case of make-ssl-client-stream) or server (in the case of make-ssl-server-stream). Optionally, subsequent entries in the file may be used to supply intermediate CA certificates (also known as a certificate chain).
The key argument is a string or pathname naming a file containing the private RSA key corresponding the the public key in the certificate. The file must be in PEM format. The key can be stored in an encrypted form which requires a pass phrase to read, but in that case the certificate-password must also be specified. If the key is stored in the certificate file, then you needn't specify the key argument.
The certificate-password argument, if specified, should be a string. If the private key stored with the certificate inside the file named by the certificate argument is encrypted, then this value is used as the key to decrypt it.
verify can be nil, :optional, or :required. Due to the way OpenSSL is implemented, the behavior of peer verification differs for servers and clients. Here we describe the behavior for servers. See make-ssl-client-stream for a discussion of the client behavior.
:verify nil means that the server will not ask the client to supply a certificate and will not do automatic verification if the client supplies a certificate anyway. If the client does provide a certificate, manual verification can be done using get-ssl-peer-certificate and get-ssl-verify-result.
:verify :optional means that the client will be asked to supply a certificate during SSL handshake. The certificate (if supplied) will be automatically verified during SSL handshake. If verification fails, an error will be generated during SSL handshake.
:verify :required means that the client will be asked to supply a certificate during SSL handshake. The client certificate will be automatically verified during SSL handshake. If the client does not supply a certificate or if verification of the supplied certificate fails, an error will be generated during SSL handshake.
maxdepth must be an integer (which defaults to 10) which indicates the maximum allowable depth of the certificate verification chain. If the chain exceeds this depth, an error will be generated during SSL handshake.
ca-file specifies the name of a file containing a series of trusted PEM-encoded Intermediate CA or Root CA certificates that will be used during peer certificate verification. Keep in mind that, when using on an SSL server, the subject name information for each of these certificates is supplied to the peer during SSL handshake, so you may want to keep the number of certificates listed in the file to a minimum. A file containing certificates of well-known root CAs can be found in [acl directory]/examples/ssl/ca-bundle.crt.
ca-directory specifies the name of a directory containing a series of trusted Intermediate CA or Root CA certificate files that will be used during peer certificate verification. Each file in the directory should contain one certificate. The files should be named based on the hash value of the certificate subject name. If more than one certificate with the same hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash (available via standard OpenSSL distributions) utility to create the necessary links.
ciphers: if the ciphers keyword argument is supplied, it must be a string which specifies an OpenSSL cipher list. This list determines which ciphers the SSL server will support. The strongest common entry from this list and the list supplied by the client during handshake will be used. If there is no entry in common, SSL handshake will fail and an error will be generated.
For details on the cipher list format, see the CIPHER LIST FORMAT section of http://www.openssl.org/docs/apps/ciphers.html.
This argument is not used with TLS 1.3. See the ciphersuites argument below.
ciphersuites: used by TLS 1.3. See TLS 1.3 support and ciphersuites in socket.html for more information and suitable values. When nil or unspecified, OpenSSL defaults are used.
crl-check: this argument controls certificate revocation list (CRL) checking. Its value may be nil (the default) for no CRL checking, t for CRL checking of the peer's certificate (if provided by the peer), or :all for CRL checking of all components of the peer's supplied certificate chain. If this argument is non-nil, the verify argument must also be non-nil. If you enable CRL checking, you must supply a proper PEM-encoded CRL, even if it contains zero revocations. If you do not supply a CRL, peer verification will never succeed.
crl-file: this argument specifies the location of a PEM-encoded CRL file. If nil or not supplied, defaults to the value of the ca-file argument (if supplied). It is acceptable for CRL to be included amongst other PEM-encoded certificates.
prefer-server-cipher-order: the value should be true or nil. The typical behavior when choosing a cipher during an SSLv3 or TLSv1 handshake is to use the client's preference. If this argument is true (the default is nil), the server's preference will be used.
See make-ssl-client-stream. See also socket.html for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.
Function, acl-socket package
Arguments: file &key (host "localhost") (user "anonymous") (password (format nil "~[email protected]" (sys:user-name))) (direction :input) debug (mode :binary) passive
This function creates a stream to/from the given file on the given host using the given user and password for authentication.
The keyword arguments are:
:input (the default), :output, or :directory. :directory returns an input stream containing a directory listing.:binary (the default), or :text. :text mode lines end with cr-lf (the internet standard).Generic Function, acl-socket package
Arguments: sock size &key buffer extract
This generic function is used to read from a datagram socket. You must specify a size bigger than the size of the message you expect (usually the rest of the datagram will be thrown away if it doesn't all fit).
If the buffer argument is given then it should be a Lisp vector of some raw type (like (unsigned-byte 8) but definitely not t) of at least size bytes that will be used to read in the datagram. If buffer is not given then a fresh buffer will be created (of the type appropriate to the format of the socket).
The buffer argument may be a character vector. In this case receive-from will create a temporary buffer of type (unsigned-byte 8) into which to read the octets and then octets-to-string will be used to convert those octets to characters. If you want to save the creation of this temporary array for each call to receive-from you should pass an (unsigned-byte 8) array in as the buffer. When using an 8-bit character Lisp (e.g., alisp8 or mlisp8-- see Allegro CL Executables: alisp, alisp8, mlisp, mlisp8, allegro, allegro-ansi in startup.html), no temporary buffer is created and no conversion occurs.
If extract is unspecified or nil then the first value returned is the buffer used to read the data. If extract is true then the first value returned is a subsequence of the buffer, that subsequence being that part of the buffer that contains the data just read.
The second value returned is the number of bytes read by receive-from.
In the case of an :internet socket, the third value returned is the 32-bit internet address or the IPv6 address of the sender of the data and the fourth value is the port number.
In the case of a :file socket, the third (and last) value returned is the filename of the sender's socket (or "" if there is no filename).
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: af-file
Returns the remote filename of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: af-internet
Returns an IP address. You can use ipaddr-to-dotted or ipaddr-to-hostname to make a more readable version of this value if you plan to print it out.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: af-internet
Returns the remote port of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: sock buffer size &key remote-host remote-port ipv6 scope-id
For datagram sockets you can't do normal Lisp stream I/O. The data is written to the socket using this function.
The buffer argument can be a string or a byte vector; the size argument is the number of bytes of data to send. (The buffer argument is actually passed unmodified to a foreign function that will grab bytes from the address, so any simple 1-d Lisp array with any element size can in principle work, given the right byte count, provided sender and receiver have the same endianess.)
remote-host and remote-port describe where to send the data. If they aren't given then the values saved when the socket was created with make-socket are used.
The ipv6 and scope-id keyword arguments are part of IPv6 support. ipv6 defaults to the value of *ipv6*. This keyword argument is passed on to lookup-hostname when resolving remote-host.
scope-id specifies the interface to use when sending IPv6 traffic 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.
Method for file-datagram-socket
Arguments (sock file-datagram-socket) buffer size &key remote-filename
The method for file-datagram-sockets is like the method for datagram sockets described above, except it is used for sockets within the address family :file.
The method for file-datagram-socket is unaffected by the IPv6 changes. file-datagram sockets are not internet sockets so they cannot use IPv6 (or IPv4) addresses.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: str to
Because socket formats are not used (see socket-format), this generic function has no effect.
See socket.html for general information on sockets in Allegro CL.
Function, acl-socket package
Arguments: socket &key reuse-address broadcast keepalive nodelay oob-inline receive-buffer-size send-buffer-size tcp-keepalive-idle-time tcp-keepalive-probe-interval tcp-keepalive-max-probes
Sets system socket options for this socket.
The meanings of most of the options are described in the description of make-socket. The various tcp-keepalive-* options are described below.
The following are boolean options, and so specifying a true value turns them on and specifying nil turns them off. If you do not specify a value for one of these options, then the value is not changed.
receive-buffer-size and send-buffer-size take integer arguments. Again, not specifying a value leaves it unchanged.
Note that certain options only work with certain kinds of sockets (e.g. broadcast only works for datagram sockets). See the description of make-socket for more information on what works with what sort of socket.
The tcp-keepalive-idle-time, tcp-keepalive-probe-interval, and tcp-keepalive-max-probes keywords set socket options defined by the C constants TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT on operating systems where they are supported (none is supported on Solaris, TCP_KEEPIDLE is not supported on macOS). The values should be integers (defaults 7200, 75, and 9 respectively). See the tcp(7) UNIX man page for more information.
It is an error to try to specify a value of an unsupported value. Thus (socket:set-socket-options socket :tcp-keepalive-idle-time 1) will signal an error on Solaris and macOS.
See socket.html for information on sockets.
Generic Function, acl-socket package
Arguments: socket address key &key (external-format :default)
This function only works on Linux. If executed on a non-Linux host, an error will be generated.
This function provides an interface to the TCP_MD5SIG (RFC2385) socket option. It sets the key to be used for TCP connections from address. This function can be called multiple times to set up keys for different addresses.
socket must be a passive stream socket (as created by (make-socket :connect :passive ...)). See make-socket.
address must be an IP address.
key must be a string or octet array.
If key is a string, external-format can supplied to specify a non-default external format for the string. The string will not be null-terminated.
See socket.html.
Generic Function, acl-socket package
Arguments: sock &key direction
sock is a socket currently connected to another socket. The value of the direction must be specified either :input or :output. Note that direction defaults to nil which is not a legal value. shutdown will signal an error if direction is not specified either :input or :output.
shutdown closes down the specified half of the bidirectional socket connection. It does not force out unflushed buffers first (as the close function does).
Calling shutdown on a socket twice, once for :input and once for :output will cause the operating system file descriptor associated with the socket to be closed. Thus you need not call the Lisp function close. Note it is not an error to call close; it will just do nothing.
This function is useful in many socket applications.
For example:
(setq sock (make-socket :remote-host "foo" :remote-port 1234))
(format sock "are you ok?~%")
(force-output sock)
(shutdown sock :direction :output)
(read sock)Calling shutdown in the above example causes the program at the other end of the connection to receive an End of File indication. Some programs, when they receive an End of File, formulate and send a reply back down the socket. Using shutdown rather than close allows this reply to be read.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: socket
Returns the socket address family of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: socket
Returns the type of connection for socket. The value can be :active or :passive. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: sock &key output-chunking output-chunking-eof input-chunking read-timeout write-timeout
This function modifies the state of the socket stream. The associated value in the argument socket of any unspecified keyword argument is not modified. Only specified keyword arguments change the state of the argument socket.
If specified, the output-chunking argument controls whether the chunking protocol will be used for output on this socket (yes if true, no if nil). If this argument is not specified, output chunking is not affected. Note that if there is data still in the output buffer for this socket stream and chunking is turned on, then the chunking protocol will be applied to the data in the buffer when it is eventually written to the socket. Therefore you may want to call force-output before turning on chunking.
If output-chunking-eof is true then this occurs:
a force-output is done to flush the socket output buffer.
a zero sized chunk message is sent to the socket, which causes the process at the other end of the socket connect to interpret this as a chunking end of file.
chunking for this socket is turned off (as if socket-control were called with :output-chunking nil)
If specified, the input-chunking argument controls whether data being read from the socket is interpreted as chunked data (yes if true, no if nil). If this argument is not specified, input chunking is not affected.
When input chunking is enabled a chunk end of file will cause the reading function (read-byte, read-char, read-sequence) to return just as if a real end of file was reached. In order to distinguish a real end of file from a chunking end of file, when a chunking end of file occurs the socket code will signal the condition excl::socket-chunking-end-of-file with the format-arguments slot being a list whose sole member is the stream that received the chunking end of file. This condition is not an error or warning, thus if it isn't caught Lisp will simply ignore it.
Timeout arguments
If specified, the value timeout arguments read-timeout and write-timeout should be nil or a positive real number. If nil, reads or writes will not timeout (except possibly because of other timeouts specified by other tools). If the value is a positive real number, attempted reads (when read-timeout is not nil) and attempted writes (when write-timeout is not nil) will timeout if the time is exceeded and the system will signal a socket-error.
Specifying timeout can be important for SSL streams (such as created by make-ssl-client-stream and make-ssl-server-stream) because read from and writes to a socket stream will not timeout when executed in a sys:with-timeout body (see the description of sys:with-timeout for more information). Reads from and writes to an SSL stream are done by breaking the data to be read/written into blocks and then processing the blocks one at a time. Note: the timeout values for SSL streams apply to the reading/writing time for individual blocks ony, not to the entire read or write.
Note that if reading from/writing to an SSL stream times out and an error is signaled, it is very likely the SSL stream will be in a broken state and should be closed (with the abort keyword argument to close specified true).
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: socket
Starting in 6.0, all sockets have :multivalent format and this function always returns :multivalent.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: sock
Return the operating system file descriptor associated with this socket. This is useful if you want to do some socket processing in foreign code and that code needs to access the socket directly. Note: Such accessing will likely confuse the buffering done by Lisp.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: socket
Returns the type of socket. Note: Both internet stream and internet datagram sockets use 16-bit port numbers. Note that stream (tcp) port N is totally distinct from datagram (udp) port N.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: stream
This function returns t but is called for its side effect, which is to initiate a handshake between SSL server and client streams.
make-ssl-server-stream and make-ssl-client-stream do not immediately initiate SSL handshake. Instead, handshake is deferred until the first I/O is made on the stream. If there are certificate verification or other errors during SSL handshake, the error will be generated during the I/O request that initiated handshake.
In some circumstances you may want to control when SSL starts. The ssl-do-handshake method initiates SSL handshake. stream must be an SSL client or server stream (such as is created by make-ssl-server-stream).
This function returns t but is called for its side effect, which is to initiate a handshake between SSL server and client streams.
make-ssl-server-stream and make-ssl-client-stream do not immediately initiate SSL handshake. Instead, handshake is deferred until the first I/O is made on the stream. If there are certificate verification or other errors during SSL handshake, the error will be generated during the I/O request that initiated handshake.
In some circumstances you may want to control when SSL starts. The ssl-do-handshake method initiates SSL handshake. stream must be an SSL client or server stream (such as is created by make-ssl-server-stream and ) and make-ssl-client-stream).
Peer certificate verification (if requested) occurs during SSL handshake. If verification fails, an error will be generated.
See socket.html.
Macro, acl-socket package
Arguments: &rest body
A call to make-socket can take a while (maybe a minute or two) to make or fail to make a connection.
If you want to limit the amount of time spent in the make-socket call you can write it with a with-timeout. If the timeout occurs, then the program gives up on trying to make the connection. However the connection is offically still pending and operating system resources will continue to be used. Thus, it's important to clean up after a timed out attempt to make a connection.
The best way to ensure that things are cleaned up is to use with-pending-connect. Just write your code something like this:
(socket:with-pending-connect
(sys:with-timeout (10 (error "connect failed"))
(socket:make-socket
:remote-host "foo.com" :remote-port 1234)))The with-pending-connect wraps the body with an unwind-protect that will clean up the pending connection as control passes through it.
See socket.html for general information on sockets in Allegro CL.
Generic Function, acl-socket package
Arguments: stream
This function returns the value of the issuer slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains information about the issuer (i.e., signer) of the certificate. The issuer information is represented as a list of attribute/value conses. The car of each cons is a string representing the attribute type ("CN", "ST", "L", "O", "OU", "CN", etc.) and the cdr of each cons is a string representing the value of the attribute.
See socket.html.
Generic Function, acl-socket package
Arguments: stream
This function returns the value of the not-after slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains the expiration date of the certificate, in universal time format.
See socket.html.
Generic Function, acl-socket package
Arguments: stream
This function returns the value of the not-before slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains the beginning validity date of the certificate, in universal time format.
See socket.html.
Generic Function, acl-socket package
Arguments: stream
This function returns the value of the serial-number slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains the serial number of the certificate, in integer form.
See socket.html.
Generic Function, acl-socket package
Arguments: stream
This function returns the value of the subject slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains information about the subject of the certificate (i.e., the entity to which the certificate belongs). The subject information is represented in the same way as the issuer information (see x509-certificate-issuer).
See socket.html.
Generic Function, acl-socket package
Arguments: stream
This function returns the value of the subject-alt-name slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot contains information about the subjectAltName extension information which may be part of v3 certificates. If available, the subjectAltName information is represented as a list of attribute/value conses. The car of each cons is a string representing the type of subjectAltName (such as "DNS"). The cdr of each cons is a string representing the attribute value.
See socket.html.
Generic Function, acl-socket package
Arguments: stream
This function returns the value of the version slot of a x509-certificate object. (It can also be used to set the value but setting it has no effect at the moment.) This slot typically contains a keyword indicating the version number of the certificate. The value will be either :v1, :v2, or :v3. If the version number of the certificate is not recognized, this slot will contain the raw integer supplied in the certificate.
The version number indicates the format of the certificate. Most certificates seen these days will be version 3 certificates (:v3).
See socket.html.
Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.
|
Allegro CL version 11.0 | ||||||||