|
<!-- 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
|
|
<tinyclipboard.h></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’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’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’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’s content was advertised as text,
|
|
but was invalid UTF-16 (in contrast to <b>ENOTSUP</b>, which
|
|
means the clipboard’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’s clipboard.</p>
|
|
|
|
<p style="margin-left:17%; margin-top: 1em"><b>#include
|
|
<stdio.h> <br>
|
|
#include <errno.h> <br>
|
|
#include <tinyclipboard.h></b></p>
|
|
|
|
<p style="margin-left:17%; margin-top: 1em"><b>int main()
|
|
<br>
|
|
{ <br>
|
|
int len = 0; <br>
|
|
char* str = tiny_clipread(&len);</b></p>
|
|
|
|
<p style="margin-left:17%; margin-top: 1em"><b>if (str) {
|
|
<br>
|
|
printf("Read %d bytes from the clipboard: %s\n",
|
|
len, str); <br>
|
|
} <br>
|
|
else { <br>
|
|
perror("Failed to read from the clipboard"); <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’s clipboard systems
|
|
(especially X11’s) behind a set of simple, highlevel
|
|
functions that allow the programmer to uniformly access any
|
|
supported operating system’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’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’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 “selections” that can be
|
|
“owned” 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’s content. As a consequence, <i>the
|
|
clipboard’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’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ülker <m-guelker@guelkerdev.de>.</p>
|
|
<hr>
|
|
</body>
|
|
</html>
|