Project

General

Profile

Files » tiny_clipread.3.html

tiny_clipread(3) manual page - quintus, 01/13/2020 09:07 AM

 
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Mon Jan 13 08:04:16 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>tiny_clipread</title>

</head>
<body>

<h1 align="center">tiny_clipread</h1>

<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#EXAMPLES">EXAMPLES</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#AUTHOR">AUTHOR</a><br>

<hr>


<h2>NAME
<a name="NAME"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">tiny_clipread -
Read from the OS clipboard</p>

<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><b>#include
&lt;tinyclipboard.h&gt;</b></p>

<p style="margin-left:11%; margin-top: 1em"><b>char*
tiny_clipread</b>(<b>int*</b> <i>len</i>);</p>

<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">The
<b>tiny_clipread()</b> function reads arbitary data from the
operating system&rsquo;s clipboard, allocates a new string
by means of <b>malloc(3)</b>, copies the data there, and
returns the newly allocated string. In the <i>len</i>
argument it returns the number of bytes allocated and
returned. In case of failure no string is allocated,
<b>NULL</b> is returned and <i>*len</i> is left
untouched.</p>

<p style="margin-left:11%; margin-top: 1em">The returned
string is guaranteed to end with a <b>NUL</b> byte, but if
you want to handle <b>NUL</b> bytes within the clipboard
data, you should instead rely on the value returned in the
<i>len</i> argument. If <i>len</i> is <b>NULL</b>, the
argument is ignored (and you have to rely on the terminating
<b>NUL</b> of the returned string alone).</p>

<p style="margin-left:11%; margin-top: 1em">The data
returned is encoded in UTF-8 regardless of the current
locale&rsquo;s encoding. This includes Win32 systems.</p>

<p style="margin-left:11%; margin-top: 1em">The caller of
this function is obleged to <b>free(3)</b> the memory
returned.</p>

<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">On a successful
retrieval, the <b>tiny_clipread()</b> function returns a
dynamically allocated copy of the data in the operating
system&rsquo;s clipboard that must be handed to
<b>free(3)</b> once you are done with it. If the retrieval
fails, the function returns <b>NULL</b> and sets
<i>errno</i> to indicate the error.</p>

<h2>ERRORS
<a name="ERRORS"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><b>X11
systems</b> <br>
This function indicates the following errors on systems
using an X11 server for graphics management:</p>

<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">


<p><b>EAGAIN</b></p></td>
<td width="2%"></td>
<td width="78%">


<p>There is no clipboard owner currently which could be
queried for anything.</p></td></tr>
</table>

<p style="margin-left:11%;"><b>ECANCELED</b></p>

<p style="margin-left:22%;">Unexpected function failure
after using an Xlib function as advertised by a prior return
value. Encountering this <i>errno</i> value might indicate a
bug in <i>tinyclipboard</i>.</p>

<p style="margin-left:11%;"><b>ECONNREFUSED</b></p>

<p style="margin-left:22%;">Failed to connect to the X
server. This most likely means that your program is not run
from within a graphical environment (e.g., from the Linux
virtual console).</p>

<p style="margin-left:11%;"><b>ENOTSUP</b></p>

<p style="margin-left:22%;">The clipboard contains non-text
data.</p>

<p style="margin-left:11%;"><b>EOVERFLOW</b></p>

<p style="margin-left:22%;">The number of bytes in the
clipboard was too large to be stored in an <b>int</b>. X11
supports much larger clipboard texts (actually <b>unsigned
long</b> bytes long ones), but <b>int</b> is the only type
that works cross-platform for all clipboard APIs and is thus
the maximum capacity supported by <i>tinylcipboard</i>.</p>

<p style="margin-left:11%; margin-top: 1em"><b>Win32
systems</b> <br>
This function indicates the following errors on Windows
systems:</p>

<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">


<p><b>EAGAIN</b></p></td>
<td width="2%"></td>
<td width="78%">


<p>Another process has opened the clipboard currently.</p></td></tr>
</table>

<p style="margin-left:11%;"><b>ECANCELED</b></p>

<p style="margin-left:22%;">Unexpected function failure
after using a Windows API function as advertised by a prior
return value. Encountering this <i>errno</i> value might
indicate a bug in <i>tinyclipboard</i>.</p>

<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">


<p><b>EILSEQ</b></p></td>
<td width="2%"></td>
<td width="78%">


<p>The clipboard&rsquo;s content was advertised as text,
but was invalid UTF-16 (in contrast to <b>ENOTSUP</b>, which
means the clipboard&rsquo;s content was not even advertised
as text).</p></td></tr>
</table>

<p style="margin-left:11%;"><b>ENOTSUP</b></p>

<p style="margin-left:22%;">The clipboard contains non-text
data.</p>

<h2>EXAMPLES
<a name="EXAMPLES"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><b>Reading a
string from the clipboard</b> <br>
This example reads an ordinary string from the operating
system&rsquo;s clipboard.</p>

<p style="margin-left:17%; margin-top: 1em"><b>#include
&lt;stdio.h&gt; <br>
#include &lt;errno.h&gt; <br>
#include &lt;tinyclipboard.h&gt;</b></p>

<p style="margin-left:17%; margin-top: 1em"><b>int main()
<br>
{ <br>
int len = 0; <br>
char* str = tiny_clipread(&amp;len);</b></p>

<p style="margin-left:17%; margin-top: 1em"><b>if (str) {
<br>
printf(&quot;Read %d bytes from the clipboard: %s\n&quot;,
len, str); <br>
} <br>
else { <br>
perror(&quot;Failed to read from the clipboard&quot;); <br>
return 1; <br>
}</b></p>

<p style="margin-left:17%; margin-top: 1em"><b>/* Do not
forget to free the returned pointer. */ <br>
free(str);</b></p>

<p style="margin-left:17%; margin-top: 1em"><b>return 0;
<br>
}</b></p>

<h2>NOTES
<a name="NOTES"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">The clipboard
is a highly operating-system specific resource. The
<i>tinyclipboard</i> library strives to hide the
complexities of certain system&rsquo;s clipboard systems
(especially X11&rsquo;s) behind a set of simple, highlevel
functions that allow the programmer to uniformly access any
supported operating system&rsquo;s clipboard system. This
highlevel interface sacrifices access to some more granular
features each of the respective systems provides, but if you
need these, you should probably not be using a
cross-platform clipboard library anyway.</p>

<p style="margin-left:11%; margin-top: 1em">Across all
operating systems and graphics stacks, the
<b>tiny_clipread()</b> function does not require your
application to be a GUI application. However, it opens
invisible windows to interact with the clipboard if it is
required. From this follows that while you do not have to
create your application as a GUI application, you have to
link in your system&rsquo;s native graphics library (e.g.,
<b>-lX11</b> on Linux) and your users must be running your
program in their graphical environment. Running your program
from a Linux virtual console will not work (the function
will return -1 and set <i>errno</i> to
<b>ECONNREFUSED</b>).</p>

<p style="margin-left:11%; margin-top: 1em">What follows
are descriptions of certain problems that arise with any one
supported operating system&rsquo;s clipboard system.</p>


<p style="margin-left:11%; margin-top: 1em"><b>Unix/X11</b>
<br>
The X11 clipboard system is really complex. It consists of
three so-called &ldquo;selections&rdquo; that can be
&ldquo;owned&rdquo; at any time by any X client. The owner
of such a selection is responsible for serving the requests
other X clients make to him for access of the
clipboard&rsquo;s content. As a consequence, <i>the
clipboard&rsquo;s content is not a global resource on
X11</i>. Global is only the knowledge of the client owning
the selection. Due to this ownership system, the content of
any selection vanishes if the owner X11 connection dies (=
the window closes).</p>

<p style="margin-left:11%; margin-top: 1em">The three
selections are called <b>PRIMARY</b>, <b>SECONDARY</b>, and
<b>CLIPBOARD</b>. The first two are unique to X11 and have
no counterpart on other graphics systems; the <b>PRIMARY</b>
selection can be set in most applications by marking text
with the mouse cursor, and retrieved by pressing the middle
mouse button. The <b>SECONDARY</b> selection is not used by
anybody. The <b>CLIPBOARD</b> selection is usually accessed
via pull-down menus or the well-known key combinations
<b>CTRL+C</b> and <b>CTRL+V</b>; this is the only selection
<i>tinyclipboard</i> gives you access to for the sake of
simplicity. It is also the only selection that ordinary
users know about.</p>

<p style="margin-left:11%; margin-top: 1em"><b>Win32</b>
<br>
The clipboard system on Windows is modelled around a global
pointer as a resource shared between multiple applications.
When an application wants to write to the clipboard, it
first opens the global clipboard resource, excluding
everybody else from accessing it (even for read access). It
then empties the clipboard, which causes the Win32
system&rsquo;s OS kernel to free the previous global pointer
(yes, the pointer is freed by the kernel, not by the
application). The kernel immediately afterwards assigns
ownership of the clipboard to the calling process, which is
now obleged to allocate a new buffer, store its data in it,
and hand the pointer to this buffer over to the clipboard
system. When done, the process closes the clipboard, but
formally remains owner of the clipboard until another
process wants to write into the clipboard or it exits. As
far as I was able to see, this ownership does not involve
any duties if one does not use delayed rendering (which
<i>tinyclipboard</i> does not do).</p>

<p style="margin-left:11%; margin-top: 1em">Since the OS
kernel manages the memory of the clipboard content, the
content does not vanish if the application closes as it does
with X11 (see above).</p>

<p style="margin-left:11%; margin-top: 1em">In contrast to
X11 (and even <b>tiny_clipwrite(3)</b> and
<b>tiny_clipnwrite(3)</b> on Win32 systems) read access to
the clipboard does not require an (invisible) window to be
created, but merely acquiring the clipboard for a moment. On
Windows, reading the clipboard thus does not involve any GUI
functionality.</p>

<p style="margin-left:11%; margin-top: 1em">It appears to
be possible to write <b>NUL</b> bytes into the Windows
clipboard, but it is impossible to retrieve them again from
there as the clipboard functions available from the Win32API
do not support querying the size of the clipboard. They
assume any text on the clipboard is terminated with a
<b>NUL</b> byte. For the sake of portability, you should
thus refrain from using <b>NUL</b> bytes in your clipboard
content if your application needs to run on Windows.</p>

<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>



<p style="margin-left:11%; margin-top: 1em"><b>tiny_cipwrite(3)
tiny_clipnwrite(3)</b></p>

<h2>AUTHOR
<a name="AUTHOR"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">The
<i>tinyclipboard</i> library was written by Marvin
G&uuml;lker &lt;m-guelker@guelkerdev.de&gt;.</p>
<hr>
</body>
</html>
(2-2/4)