wl_display_connect man page

wl_display_connect, wl_display_connect_to_fd — Connect to a Wayland socket

Synopsis

#include <wayland-client.h>

struct wl_display *wl_display_connect(const char *name);

struct wl_display *wl_display_connect_to_fd(int fd);

Description

wl_display_connect connects to a Wayland socket that was previously opened by a Wayland server. The server socket must be placed in XDG_RUNTIME_DIR when WAYLAND_DISPLAY (or name, see below) is a simple name, for this function to find it. The server socket is also allowed to exist at an arbitrary path; usage details follow. See below for compatibility issue details.

The name argument specifies the name of the socket or NULL to use the default (which is "wayland-0"). The environment variable WAYLAND_DISPLAY replaces the default value. If name is an absolute path, then that path is used as the Wayland socket to which the connection is attempted. Note that in combination with the default-value behavior described above, this implies that setting WAYLAND_DISPLAY to an absolute path will implicitly cause name to take on that absolute path if name is NULL. If WAYLAND_SOCKET is set, this function behaves like wl_display_connect_to_fd with the file-descriptor number taken from the environment variable.

Support for interpreting WAYLAND_DISPLAY as an absolute path is a change in behavior compared to wl_display_connect's behavior in versions 1.14 and older of Wayland. It is no longer guaranteed in versions 1.15 and higher that the Wayland socket chosen is equivalent to manually constructing a socket pathname by concatenating XDG_RUNTIME_DIR and WAYLAND_DISPLAY. Manual construction of the socket path must account for the possibility that WAYLAND_DISPLAY contains an absolute path.

wl_display_connect_to_fd connects to a Wayland socket with an explicit file-descriptor. The file-descriptor is passed as argument fd.

Return Value

wl_display_connect and wl_display_connect_to_fd return a new display context object or NULL on failure. errno is set correspondingly.

See Also

wayland-client(7), wl_display_disconnect(3), wl_display_iterate(3)

Info

September 2012 wayland-client wl_display_connect