1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4 5<!-- 6 Written 2012 by David Herrmann <dh.herrmann@googlemail.com> 7 Dedicated to the Public Domain 8--> 9 10<refentry id="wl_display_connect"> 11 <refentryinfo> 12 <title>wl_display_connect</title> 13 <productname>wayland-client</productname> 14 <date>September 2012</date> 15 <authorgroup> 16 <author> 17 <contrib>Developer</contrib> 18 <firstname>David</firstname> 19 <surname>Herrmann</surname> 20 <email>dh.herrmann@googlemail.com</email> 21 </author> 22 </authorgroup> 23 </refentryinfo> 24 25 <refmeta> 26 <refentrytitle>wl_display_connect</refentrytitle> 27 <manvolnum>3</manvolnum> 28 </refmeta> 29 30 <refnamediv> 31 <refname>wl_display_connect</refname> 32 <refname>wl_display_connect_to_fd</refname> 33 <refpurpose>Connect to a Wayland socket</refpurpose> 34 </refnamediv> 35 36 <refsynopsisdiv> 37 <funcsynopsis> 38 39 <funcsynopsisinfo>#include <wayland-client.h></funcsynopsisinfo> 40 41 <funcprototype> 42 <funcdef>struct wl_display *<function>wl_display_connect</function></funcdef> 43 <paramdef>const char *<parameter>name</parameter></paramdef> 44 </funcprototype> 45 46 <funcprototype> 47 <funcdef>struct wl_display *<function>wl_display_connect_to_fd</function></funcdef> 48 <paramdef>int <parameter>fd</parameter></paramdef> 49 </funcprototype> 50 51 </funcsynopsis> 52 </refsynopsisdiv> 53 54 <refsect1> 55 <title>Description</title> 56 <para><function>wl_display_connect</function> connects to a Wayland socket 57 that was previously opened by a Wayland server. The server socket must 58 be placed in <envar>XDG_RUNTIME_DIR</envar> when <envar>WAYLAND_DISPLAY</envar> 59 (or <varname>name</varname>, see below) is a simple name, for this 60 function to find it. The server socket is also allowed to exist at an 61 arbitrary path; usage details follow. See below for compatibility issue 62 details.</para> 63 64 <para>The <varname>name</varname> argument specifies the name of 65 the socket or <constant>NULL</constant> to use the default (which is 66 <constant>"wayland-0"</constant>). The environment variable 67 <envar>WAYLAND_DISPLAY</envar> replaces the default value. 68 69 If <varname>name</varname> is an absolute path, then that path is used 70 as the Wayland socket to which the connection is attempted. Note that 71 in combination with the default-value behavior described above, this 72 implies that setting <envar>WAYLAND_DISPLAY</envar> to an absolute 73 path will implicitly cause <varname>name</varname> to take on that 74 absolute path if <varname>name</varname> is <constant>NULL</constant>. 75 76 If <envar>WAYLAND_SOCKET</envar> is set, this function behaves like 77 <function>wl_display_connect_to_fd</function> with the file-descriptor 78 number taken from the environment variable.</para> 79 80 <para>Support for interpreting <envar>WAYLAND_DISPLAY</envar> as an 81 absolute path is a change in behavior compared to 82 <function>wl_display_connect</function>'s behavior in versions 83 1.14 and older of Wayland. It is no longer guaranteed in versions 84 1.15 and higher that the Wayland socket chosen is equivalent to 85 manually constructing a socket pathname by concatenating 86 <envar>XDG_RUNTIME_DIR</envar> and <envar>WAYLAND_DISPLAY</envar>. 87 Manual construction of the socket path must account for the 88 possibility that <envar>WAYLAND_DISPLAY</envar> contains an absolute 89 path.</para> 90 91 <para><function>wl_display_connect_to_fd</function> connects to a Wayland 92 socket with an explicit file-descriptor. The file-descriptor is passed 93 as argument <varname>fd</varname>.</para> 94 </refsect1> 95 96 <refsect1> 97 <title>Return Value</title> 98 <para><function>wl_display_connect</function> and 99 <function>wl_display_connect_to_fd</function> return a new display 100 context object or NULL on failure. <varname>errno</varname> is set 101 correspondingly.</para> 102 </refsect1> 103 104 <refsect1> 105 <title>See Also</title> 106 <para> 107 <citerefentry><refentrytitle>wayland-client</refentrytitle><manvolnum>7</manvolnum></citerefentry>, 108 <citerefentry><refentrytitle>wl_display_disconnect</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 109 <citerefentry><refentrytitle>wl_display_iterate</refentrytitle><manvolnum>3</manvolnum></citerefentry> 110 </para> 111 </refsect1> 112</refentry> 113