API Reference

Every exported symbol of the cl-wl package. For the generated protocol packages see Protocol Bindings. For cl-wl/test-compositor see Testing with the Test Compositor, for cl-wl/scanner see The Scanner, and for cl-wl/ffi see Raw FFI Layer.

Every exported function declaims an ftype that gives each argument its full type, such as a range or (or null string). SBCL checks it on entry, so a wrong argument signals a type-error that names the argument, and SBCL warns at compile time where it can tell. What a type cannot say, such as an event the interface lacks or a destroyed proxy, signals the conditions under Errors.

Displays

connect &optional name → display

Connects to the Wayland display name (a string such as "wayland-1"), or, if name is NIL, to the one named by $WAYLAND_DISPLAY (default "wayland-0"). Signals connection-error if no connection can be made.

connect-to-fd fd → display

Connects over fd, an already-connected socket. The display takes ownership of fd and closes it on disconnect. Signals connection-error if the connection cannot be set up.

disconnect display → no values

Destroys every proxy of display on the client side, closes the connection and frees its foreign memory. Disconnecting a closed display does nothing. Afterwards the display is dead like a destroyed proxy, and using it signals destroyed-proxy-error.

with-display (variable &optional name) &body body

Evaluates body with variable bound to (connect name), and disconnects on exit, normal or not.

display

The class of a connection. A display is also the wl_display proxy, an instance of cl-wl/wayland:wl-display, so it is passed to wl_display requests directly.

display-fd display → fd

The connection's file descriptor, for waiting on it with poll or another event loop. It belongs to the display.

display-error display → compositor-error, connection-error or NIL

The error that broke the connection, or NIL while it works. It returns the condition and does not signal it. It may be called while another thread waits in read-events. See Errors.

Dispatching

All of these signal compositor-error or connection-error once the connection has failed. Those that deliver events also signal event-error for an event that could not be decoded. See Event Loops.

dispatch display &key timeout → count

Sends buffered requests, waits until events arrive or timeout seconds pass (NIL: no limit; 0: don't wait), reads them, and runs their handlers. Returns the number of events delivered.

dispatch-pending display → count

Runs the handlers of events that have already been read, without reading or waiting.

roundtrip display → count

Sends buffered requests, blocks until the compositor has processed them, then delivers every event received in the meantime.

read-events display &key timeout → boolean

Sends buffered requests, waits until events arrive or timeout seconds pass, and reads them without delivering them. Returns true if there may be events for dispatch-pending. If events had already been read, it returns true at once. This is the one function that may run while another thread uses the display.

flush display → no values

Sends buffered requests. If the socket is full, the rest stay buffered and are sent by the next dispatch.

Globals

See Globals.

bind display class &key version (errorp t) → proxy or NIL

Binds the compositor's global of the interface whose proxy class is class, such as 'wl-compositor. The version is the highest that the compositor, the bindings and version all allow. If several globals exist, the first announced is bound. If none exists, it signals missing-global-error, or returns NIL when errorp is false.

bind-all display class &key version → list of proxies

Binds every global of the interface that is offered now.

follow-globals display class &key version added removed → global-follower

Binds every global of the interface, now and as they are announced, and calls added with each proxy. When one is withdrawn, it calls removed with its proxy, which is then the caller's to destroy. removed defaults to #'destroy-proxy and added to doing nothing. For globals offered now, added is called before follow-globals returns. For later ones, it is called while events are dispatched.

stop-following follower → no values

Ends a follow-globals. The proxies it bound stay the caller's.

global-follower

The structure follow-globals returns. Its thread rules are those of its display.

global-version display class → version or NIL

The version at which the compositor offers the interface, or NIL.

list-globals display → list

The globals offered, in announcement order, as (interface-name version) lists, such as ("wl_seat" 7).

missing-global-error, missing-global-error-interface

Signalled by bind. The reader returns the protocol name of the missing interface.

Proxies

proxy

The base class of every protocol object on the client side. Each interface's proxy class, such as cl-wl/wayland:wl-surface, is a subclass. Its thread rules are those of its display.

proxy-display proxy → display

The display the proxy belongs to. A display belongs to itself. There is no writer: a proxy stays on the display it was made on.

proxy-version proxy → version

The interface version the object was created with. Requests newer than it signal version-error.

proxy-id proxy → integer

The protocol object id. Ids are reused after objects are destroyed. Signals destroyed-proxy-error for a destroyed proxy.

proxy-interface-name proxy → string

The protocol name of the proxy's interface, such as "wl_surface".

proxy-live-p proxy → boolean

True until the proxy is destroyed.

proxy-pointer proxy → foreign pointer

The raw struct wl_proxy *, or for a display its struct wl_display *, for code that needs it, such as Vulkan surface creation. It is valid until the proxy is destroyed. An escape hatch.

borrow-proxy display pointer class → proxy

A proxy of class, such as wl-buffer, for pointer, a wl_proxy on display that other C code made and owns, such as a cursor image's wl_buffer in libwayland-cursor, so that it can be passed to requests. The inverse of proxy-pointer, and an escape hatch: cl-wl/cursor uses it. Borrowing the same object again returns the same proxy. The owner keeps the object: a borrowed proxy receives no events, and its destructor requests signal wl-error; destroy-proxy and disconnect forget it without destroying the wl_proxy. Forget it with destroy-proxy before the owner destroys the object; using it afterwards signals destroyed-proxy-error instead of touching freed memory.

destroy-proxy proxy → no values

Destroys the proxy. If its interface has a destructor request that the proxy's version has and that takes no arguments, such as wl_output.release from version 3, that request is sent. Otherwise the proxy is destroyed on the client side only, which is right for objects without one, such as wl_registry, and for versions older than their interface's destructor. Destroying a destroyed proxy does nothing. Its argument is any proxy but a display, which disconnect closes: a display signals a type-error. It does not change the order in which the protocol requires objects to be destroyed.

Events

event-handler proxy event → handler or NIL

(setf event-handler) handler proxy event

Reads or sets the function called when proxy receives event, a keyword such as :configure. The handler is called with the proxy and the event's arguments. NIL removes it. An event the interface lacks signals wl-error listing the events it has. After a destructor event, such as wl_callback's :done, the proxy is destroyed once the handler has run, or unwound.

set-event-handlers proxy &rest events-and-handlers → proxy

Sets several handlers from alternating keywords and functions.

Shared memory

shared-memory

A block of memory shared with the compositor, for wl_shm pools: an anonymous file, mapped for writing. Thread rules: one thread at a time; it belongs to no display.

make-shared-memory size → shared-memory

A new shared memory of size bytes, zeroed. Signals wl-error if the system cannot provide it.

destroy-shared-memory memory → no values

Unmaps it and closes its file. The compositor keeps its own mapping, so pools and buffers made from it live on. Destroying it twice does nothing.

with-shared-memory (variable size) &body body

Evaluates body with a new shared memory, destroyed on exit.

shared-memory-fd memory → fd

The file descriptor to pass to wl-shm-create-pool. It belongs to the memory: do not close it.

shared-memory-size memory → integer

write-shared-memory memory data &key (offset 0) → no values

Copies data, a simple vector of octets or of 32-bit pixels, into the memory at offset bytes. Pixels are written in the machine's byte order. Signals wl-error if it does not fit. Allocates nothing.

resize-shared-memory memory size → no values

Resizes the memory, keeping its contents, for wl-shm-pool-resize. Earlier pointers from shared-memory-pointer are invalid afterwards.

shared-memory-pointer memory → foreign pointer

The address the memory is mapped at, for drawing straight into it. An escape hatch.

read-keymap fd size → string

The keymap text wl_keyboard's :keymap event sends as fd and size, for cl-xkbcommon's make-keymap-from-string. Closes fd, even when it signals wl-error because the keymap cannot be read.

close-fd fd → no values

Close fd, a file descriptor an event delivered. Such a file descriptor belongs to the receiver, who must close it or hand it to a function that does, as read-keymap does. Close one you do not use, such as a keymap in a format you do not read. Signals wl-error, with the reason the system gave, if closing fails, as when fd is not open.

Pipes

The clipboard's data moves through pipes; see Recipes.

make-pipe → read-fd, write-fd

The read and write ends of a new pipe, both closed on exec, so a child process never holds one open. For a request that takes a file descriptor to write data into, such as wl_data_offer.receive: pass it the write end, flush, close the write end with close-fd, and read the data from the read end with receive-text. Signals wl-error if no pipe can be made.

receive-text fd &key (timeout 1) → string or NIL

Read the UTF-8 text the other side writes into fd, until it closes its end, and close fd. Returns the text, which ends at a null byte if there is one, or nil if timeout seconds (nil: no limit) pass first. Signals wl-error if reading fails or the text is not UTF-8; fd is closed then too.

send-text fd text &key (timeout 1) → boolean

Write text in UTF-8 into fd, the pipe wl_data_source's :send event delivers, and close fd. Returns true once it is all written, or false if the reader closed its end first or timeout seconds (nil: no limit) passed, so a reader that does not read never holds the caller longer. It writes after poll, in chunks no larger than PIPE_BUF, so a write never blocks. Signals wl-error if writing fails otherwise; fd is closed then too.

Enums

enum-value enum value → integer

The integer for value in the enum type enum. value is a keyword, a list of keywords for a bitfield, or an integer, which is returned unchanged. An unknown keyword signals a type-error that lists the valid ones.

enum-keywords enum integer → keyword, list or integer

The reverse: a keyword for a plain enum, or a list of keywords for a bitfield. An unknown value is returned as an integer. In a bitfield, the unknown bits are appended to the list as one integer.

Introspection

find-proxy-class wire-name → class or NIL

The proxy class of the interface named wire-name, such as "wl_compositor", or NIL if no loaded bindings define it.

interface-wire-name class → string

The protocol name of the interface whose proxy class is class.

supported-version class → version

The newest version of the interface that the loaded bindings support. bind never binds a newer one.

interface-requests class → list of message

interface-events class → list of message

The interface's requests or events, as a fresh list in opcode order.

message

A request or event. Read-only. Readers:

Reader	Value
message-name	the request function's symbol, or the event's keyword
message-wire-name	the protocol's name, such as "attach"
message-opcode	its opcode
message-since	the interface version that introduced it
message-destructor-p	true for a request that destroys its object, or an event after which it is gone
message-arguments	a list of argument in wire order

argument

An argument of a message. Read-only. Readers:

Reader	Value
argument-name	a symbol
argument-type	:int, :uint, :fixed, :string, :object, :new-id, :array or :fd
argument-interface	the proxy class of an object argument, or NIL if any is allowed
argument-allow-null-p	true if it may be null
argument-enum	the enum type of its values, or NIL
argument-element	for an array of 32-bit values, :int or :uint; else NIL

Interface tables

For code that talks to libwayland directly, such as a compositor built on libwayland-server. Displays manage their own tables.

interface-tables, make-interface-tables

A set of foreign wl_interface tables, built on demand. One thread at a time.

interface-pointer tables class → foreign pointer

The wl_interface for the proxy class class, built in tables on first use with every interface it refers to. Valid until the tables are freed. An escape hatch.

free-interface-tables tables → no values

Frees every table. The tables may be used again afterwards.

Types

fixed

(real -8388608 (8388608)): a number that fits Wayland's 24.8 fixed point. Requests round to the nearest 1/256, and events deliver single-floats.

fd

(integer 0 2147483647): a file descriptor. One passed in a request is duplicated, so you keep it. One delivered in an event is yours to close.

Conditions

See Errors for when each is signalled.

Condition	Parent	Readers
wl-error	error	wl-error-message
connection-error	wl-error	connection-error-errno (integer or NIL)
compositor-error	wl-error	compositor-error-interface (string), compositor-error-object-id, compositor-error-code
version-error	wl-error	version-error-required, version-error-available
destroyed-proxy-error	wl-error	destroyed-proxy-error-proxy
event-error	wl-error	event-error-cause (the condition signalled while decoding)
missing-global-error	wl-error	missing-global-error-interface

Definitions used by generated bindings

You only need these when writing bindings by hand. The scanner emits them. See The Scanner.

define-enum name (interface wire-name &key bitfield) documentation &body entries

Defines name as a type whose values are the entries' keywords, or lists of them for a bitfield, and registers the enum for enum-value and event decoding. Each entry is (keyword value).

define-interface name (wire-name version) documentation &body events

Defines name as a proxy class, a subclass of display for "wl_display" and of proxy otherwise, and registers the interface and its events. Each event is (keyword opcode wire-name [:destructor t] . args); :destructor t marks an event after which the object is gone.

define-request name (interface wire-name opcode &key since destructor) documentation &body args

Defines name as the function that sends a request. It declaims the function's ftype, checks its arguments, checks the proxy's version against since, and destroys the proxy afterwards if destructor is true. Each arg is (name type &key interface allow-null enum element), where type is one of :int :uint :fixed :string :object :new-id :array :fd. When the form is expanded, it signals wl-error if two of the function's parameters would share a name, or if the request would create more than one object.