Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the fsocket Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:46:50 2022 GMT+0.
Next: Systems, Previous: The fsocket Reference Manual, Up: The fsocket Reference Manual [Contents][Index]
This is yet-another Common Lisp FFI to provide a portable sockets API. It is intended to offer a socket API that wraps at a very low level the underlying BSD-sockets API provided by the host OS. Only supports the standard blocking I/O calls, does not support overlapped or aio_ type asynchronous calls.
Basically you write exactly the same sort of code you would if writing in C.
;; open the socket
(let ((fd (open-socket :type :datagram)))
(socket-bind fd (make-sockaddr-in))
;; do something with the socket
;; close it
(close-socket fd))
There are two types of I/O: send/recv for connected sockets and sendto/recvfrom for unconnected sockets.
(let ((fd (open-socket :type :datagram))
(buffer (make-array 1024)))
(socket-bind fd (make-sockaddr-in :port 9000))
(multiple-value-bind (count raddr) (socket-recvfrom fd buffer)
(format t "Received ~A bytes from ~A~%" count raddr)
(socket-sendto fd buffer raddr :end count))
(close-socket fd))
The 4 I/O functions also accept a foreign pointer instead of an octet vector as the buffer parameter. This allows callers to avoid the copy to and from foreign memory. This is somewhat more awkward to use but for certain applications could prove useful.
Provides an API based on POSIX poll(). On systems where this is available (i.e. everywhere except Windows) it calls directly to poll(). On Windows it calls WSAEnumNetworkEvents() and iterates over each socket. The Windows events are mapped to poll events.
(let ((pc (open-poll)))
(poll-register pc (make-instance 'pollfd :fd fd :events (poll-events :pollin)))
(doevents (pollfd event) (poll pc :timeout 1000)
;; process the events
)
(close-poll pc))
These contain a list of IP addresses associated with the adapter (i.e. logical interfaces), the physical address of the adapter, the interface index and current status.
The currently supported socket options are as follows.
Socket options :SOCKET
:ACCEPTCONN boolean:BROADCAST boolean:REUSEADDR boolean:SNDBUF integer:RCVBUF integer:SNDTIMEO integer:RCVTIMEO integerIP options :IP
:IP-MULTICAST-LOOP boolean:IP-MULTICAST-IF 4-octet array:IP_MULTICAST_TTL integer:MCAST-JOIN-GROUP (index addr) where index is the interface index and addr is the multicast addressTCP options :TCP
:NODELAY booleanVarious advanced usage topics here.
FSOCKET provides a portable polling mechanism based on POSIX poll(). On those systems is calls poll() directly, but on Windows we need a little bit more work. In order to provide a uniform interface on all platforms we must do the following:
POLL-REGISTERPOLL-REGISTER calls WSAEventSelect, which will convert
the socket to non-blocking mode.POLL-REGISTER does nothing other than pushing the pollfd
instance onto a list of pollfds stored with the poll context.fcntl()IPv4 UDP multicast is implemented and working. See test/test2.lisp.
MULTICAST-JOIN ::= join the socket to the multicast group on all ethernet interfaces.OPEN-MULTICAST-SOCKET ::= open a socket to send multicast datagrams.When you call POLL-REGISTER you provide an instance of the class POLLFD, which encapsulates the socket and the events you wish to poll for. However, typically you will also want to associate other information with the socket, for instance and receive buffer or other contextual information. All you have to do is subclass POLLFD and provide instances of your own class to POLL-REGISTER. For an example see TCP-ECHO in test/test1.lisp where I provide different subclasses for the listening TCP socket and its connections.
There can be issues when performing UDP broadcast to address 255.255.255.255 on FreeBSD. This is due to the way FreeBSD implements UDP broadcasting, which is different to Linux and Windows in this respect.
On POSIX platforms (for fsocket, that means Linux, FreeBSD, Darwin i.e. everywhere but Windows) unix domain sockets
are also supported as a family :UNIX to OPEN-SOCKET. Currently only :STREAM type sockets are supported, datagram
type unix domain sockets may be supported at some point in the future.
Unlike :INET and :INET6 families, :UNIX sockets are addressed using a string which represents a file
on the host. Otherwise their usage is the same. See test/test-unix.lisp for an example.
On Linux platforms the BSD-sockets are extended by a SocketCAN API, which implements communication between a host OS and a CAN bus.
An application reads and sends CAN messages using SOCKET-RECV, SOCKET-RECVFROM, SOCKET-SEND and SOCKET-SENDTO after a corresponding file descriptor is created (OPEN-SOCKET) and bound (SOCKET-BIND).
It is recommended to use the macro WITH-CAN-SOCKET to safely open, bind and close CAN sockets.
All SocketCAN SEND* operations never block, all SocketCAN RECV* calls always block. Use polling to make the latter non-blocking.
Some useful examples can be found in test/test-socketcan.lisp.
Because we are calling directly into the host API using CFFI, the implementation portability issues are handled by CFFI. I intend to support Windows, Linux, FreeBSD and OSX. Currently the following have been tested. A small amount of work will be required to support other systems (e.g. checking structs have the same layout, adjusting constants etc.).
Licensed under the terms of the MIT license. Frank James 2015.
Next: Files, Previous: Introduction, Up: The fsocket Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Franks socket API
Frank James <frank.a.james@gmail.com>
MIT
Next: Packages, Previous: Systems, Up: The fsocket Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: fsocket/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
fsocket (system).
Next: fsocket/errors.lisp, Previous: fsocket/fsocket.asd, Up: Lisp [Contents][Index]
fsocket (system).
Next: fsocket/constants.lisp, Previous: fsocket/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
fsocket (system).
fsocket-error-msg (reader method).
Next: fsocket/common.lisp, Previous: fsocket/errors.lisp, Up: Lisp [Contents][Index]
errors.lisp (file).
fsocket (system).
Next: fsocket/posix.lisp, Previous: fsocket/constants.lisp, Up: Lisp [Contents][Index]
constants.lisp (file).
fsocket (system).
Next: fsocket/options.lisp, Previous: fsocket/common.lisp, Up: Lisp [Contents][Index]
common.lisp (file).
fsocket (system).
Next: fsocket/streams.lisp, Previous: fsocket/posix.lisp, Up: Lisp [Contents][Index]
posix.lisp (file).
fsocket (system).
Previous: fsocket/options.lisp, Up: Lisp [Contents][Index]
options.lisp (file).
fsocket (system).
Next: Definitions, Previous: Files, Up: The fsocket Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: Indexes, Previous: Packages, Up: The fsocket Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
Evaluate the POLL-FORM and iterate over each of the pollfds with events pending.
On each iteration, POLLFD will be bound to the associated pollfd strcuture and EVENTS will be bound
to a list of symbols naming each pending event.
Evaludate BODY with VAR bound to a poll context.
Execute the body ensuring the socket bound to VAR is closed.
Evaluate BODY with VAR bound to a connected TCP socket.
VAR ::= variable
ADDR ::= address to connect to.
Evaluate BODY with VAR bound to a listening TCP socket.
VAR ::= variable that holds the listening TCP socket.
PORT ::= port to bind socket to, defaults to the wildcard port 0.
Evaludate BODY with VAR bound to a UDP socket.
VAR ::= variable that holds the socket.
PORT ::= the port to bind VAR to, defaults to the wildcard port 0.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
mtu.
name.
type.
Close a poll context
Close the socket named by FD.
Returns a list of SOCKADDR-IN addresses for configured DNS name servers.
Returns true if the address references IPv4 127.0.0.1 or IPv6 ::1, false otherwise. ADDR ::= a SOCKADDR-IN or SOCKADDR-IN6 address structure.
Wrap a TCP connection with a gray-stream.
FD ::= TCP connection file descriptor.
Remarks: non-blocking file descriptors are not supported. This is because
the read-byte or read-sequence functions may signal an EWOULDBLOCK status
if they are not ready for a recv operation. However, if you can ensure a
recv would not block before calling read-byte or read-sequence functions
then non-blocking sockets should work.
READ-BYTE and SEND-BYTE are extremely inefficient because they call directly to recv() and send(). You should always buffer sends and call write-sequence whereever possible. There is almost never a reason to call read-byte, always call read-sequence into a buffer and wrap that in a stream.
Join the IPv4 multicast group on all ETHERNET interfaces.
Open a socket to be used to send IPv4 multicast datagrams.
ADAPTER ::= adapter to use as originating interface.
TTL ::= integer specifying multicast ttl.
LOOPBACK ::= if true, will receive datagrams sent from loopback device, if false disables loopback.
Returns the unbound socket.
Open a poll context.
Open a socket. Call CLOSE-SOCKET to free resources.
FAMILY ::= address family integer. Either :INET, :INET6, :UNIX or :CAN.
TYPE ::= socket type name, defaults to SOCK_DGRAM. Can be :datagram, :stream or :raw.
PROTOCOL ::= socket protocol integer. Usually doesn’t need to be specified.
Returns the socket file descriptor.
Open a TCP connection to ADDR.
Open a listening TCP socket bound to local port PORT, defaults to wildcard port.
Open a UDP socket bound to local port PORT, defaults to wildcard port.
Poll the sockets registered with the poll context for network events.
PC ::= poll context as returne from OPEN-POLL.
TIMEOUT ::= if supplied time in milliseconds to wait. If not supplied defaults to infinity.
Returns a list of registered pollfd structures. Users should check the REVENTS slot for pending events.
fds.
Map an event name to an event flag or vice versa.
Event predicate.
EVENT ::= event integer.
NAME ::= event name to test. If not supplied, indicates whether any event is pending.
Map an event integer to a list of event names, or a list of event names to an event integer.
Lookup the pollfd for the file descriptor.
PC ::= poll context.
FD ::= file desctipror.
Returns the pollfd with the matching file descriptor if found.
Register a pollfd descriptor with a poll context.
Unregister a pollfd descriptor from a poll context.
Allocate a SOCKADDR-IN address structure.
INADDR ::= a vector of 4 octets specifying the internet address. May be
entered in the "dotted quad" string format.
If not supplied the wildcard address is used.
PORT ::= integer specifying the port number. If not supplied port 0 will be used.
Returns a new SOCKADDR-IN structure.
addr.
port.
addr.
port.
Generate a string of format a.b.c.d:port from the address.
Accept a connection from the listening socket.
SOCK ::= listening socket.
Returns (values conn addr) where
CONN ::= new connected socket.
ADDR ::= address of the connected socket.
If the socket is in non-blocking mode and the operation would block returns nil. A :POLLIN event indicates a subsequent socket-accept will complete immediately.
Bind the socket to the local address/interface.
FD ::= socket file descriptor.
ADDR ::= local address or can interface. Can be SOCKADDR-IN, SOCKADDR-IN6 or string for internet sockets; must be of type CAN-INTERFACE for can sockets
Connect the socket to the remote address.
SOCK :: socket.
ADDR ::= remote address.
Returns true if the operation completed successfully.
If the socket is in non-blocking mode and the operation would block returns NIL.
A :POLLOUT event indicates a subsequent socket-connect will complete immediately.
Start the socket listening.
Get the address to which the socket has been bound. FD ::= socket as returned from OPEN-SOCKET. Returns a SOCKADDR-IN or SOCKADDR-IN6 structure.
Receive data from the socket.
FD ::= socket.
BUFFER ::= octet vector, foreign pointer or can-frame that receives data.
START ::= buffer start index.
END ::= buffer end index.
Retuns the number of bytes actually received, which can be less than the number requested.
Receive data from the socket.
FD ::= socket.
BUFFER ::= octet vector or foreign pointer.
START ::= start index.
END ::= end index.
Returns (values count addr) where
COUNT ::= number of octets actually received, which can be less tha nthe number requested.
ADDR ::= remote address or can-interface from which the data was received.
Send a buffer on the connected socket.
SOCK ::= connected socket.
BUFFER ::= octet vector, foreign pointer or can-frame.
START ::= start index of buffer.
END ::= end index of buffer.
Returns the number of bytes actually sent, which can be less than the requested length.
Send data to the address on the socket.
FD ::= socket.
ADDR ::= local address or can interface. Can be SOCKADDR-IN, SOCKADDR-IN6 or string for internet sockets must be of type CAN-INTERFACE for can sockets.
ADDR ::= destination address, either a SOCKADDR-IN or SOCKADDR-IN6 structure or a can-interface.
START ::= buffer start index.
END ::= buffer end index.
Returns the number of octets actually sent, which can be less than the number requested.
Shutdown traffic on the TCP socket.
HOW ::= :SEND to stop sending, :RECEIVE to stop receiving, :BOTH to stop both.
Parses a string in the format a.b.c.d[:port] i.e. a dotted quad with optional port. If the port is not specified it defaults to 0.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Get a socket option.
SOCK ::= socket.
LEVEL ::= symbol naming a level.
OPTION ::= symbol naming a socket option.
Returns the value of the named option.
Set a socket option.
SOCK ::= socket
LEVEL ::= symbol naming a socket level.
OPTION ::= symbol naming a socket option.
VALUE ::= value to set.
Set to use or not use loopback. Value is a boolean
Set the local interface to use. VALUE is a 4-octet array indicating the local address.
Set the mutlicast TTL. Value is an integer.
VALUE ::= (index address) where INDEX is the interface index and ADDRESS is the multicast address to join.
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
The element type is always OCTET by definition.
sb-gray.
sb-gray.
sb-gray.
Returns the index of last byte read.
trivial-gray-streams.
sb-gray.
trivial-gray-streams.
cffi.
cffi.
cffi.
cffi.
cffi.
cffi.
cffi.
cffi.
Next: Structures, Previous: Standalone methods, Up: Public Interface [Contents][Index]
error.
(quote nil)
:msg
This slot is read-only.
condition.
Next: Classes, Previous: Conditions, Up: Public Interface [Contents][Index]
structure-object.
common-lisp.
structure-object.
Previous: Structures, Up: Public Interface [Contents][Index]
TCP connection file descriptor/handle.
:fd
This slot is read-only.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Symbol macros, Previous: Internals, Up: Internals [Contents][Index]
Next: Ordinary functions, Previous: Symbol macros, Up: Internals [Contents][Index]
Evaluate BODY in a context where VAR is bound to the TCP file descriptor.
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
name.
data.
id.
Return a 32-bit big-endian integer
Return a 16-bit big-endian integer
Return a 16-bit integer converted from big-endian
Next: Conditions, Previous: Ordinary functions, Up: Internals [Contents][Index]
msg.
code.
TCP connection file descriptor/handle.
fd.
Next: Structures, Previous: Generic functions, Up: Internals [Contents][Index]
(quote 0)
:code
This slot is read-only.
Next: Classes, Previous: Conditions, Up: Internals [Contents][Index]
structure-object.
"any"
Previous: Structures, Up: Internals [Contents][Index]
Previous: Definitions, Up: The fsocket Reference Manual [Contents][Index]
| Jump to: | %
(
A C D F G H I L M N O P S T W |
|---|
| Jump to: | %
(
A C D F G H I L M N O P S T W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
+
A B C D E F I M N O P R S T U |
|---|
| Jump to: | *
+
A B C D E F I M N O P R S T U |
|---|
| Jump to: | A C E F G I O P R S T |
|---|
| Jump to: | A C E F G I O P R S T |
|---|