1 \cfg{man-identity}{xcopy}{1}{2004-08-02}{Simon Tatham}{Simon Tatham}
3 \title Man page for \cw{xcopy}
7 \cw{xcopy} - read and write text to/from an X selection from the
12 \c xcopy [ -r ] [ -u | -c ] [ -C ]
17 \cw{xcopy} is a command-line utility for manipulating the X selection.
19 It has two basic modes. In read mode (\cw{xcopy -r}), it connects to
20 your X server, retrieves the contents of the selection as plain
21 text, and writes it on standard output. You would then typically
22 redirect its output into a file, or pipe it into some other program.
24 In write mode (just \cw{xcopy}, if \cw{-r} is not specified), it
25 will read data from standard input, then connect to your X server
26 and place that data in the selection as plain text. So you can pipe
27 data into \cw{xcopy}, move to another application, and press Paste.
29 The X selection model requires the selection-owning client to remain
30 connected to the server and hand out its data on request. Therefore,
31 \cw{xcopy} in write mode forks off a background process which does
32 this. The background process terminates once it is no longer the
33 selection owner (i.e. as soon as you select data in another
34 application), or if your X session finishes. Normally you can ignore
35 its presence, although it might become important to be aware of it
36 if (for example) the \cw{xcopy} background process were to be the
37 last X client still connected through an SSH tunnel.
39 \cw{xcopy} currently only handles text data. However, it is capable
40 of handling it in the form of plain text, UTF-8, or compound
41 (multiple-character-set) text. Use the \cw{-u}, \cw{-c} and \cw{-C}
42 options to control this aspect of its behaviour.
46 By default (if \cw{-r} is not supplied), \cw{xcopy} operates in
51 \dd Places \cw{xcopy} into read mode.
53 By default (if neither \cw{-c} nor \cw{-u} is supplied), \cw{xcopy}
54 reads and writes the selection using the type \cw{STRING}, which
55 means that the input or output data is expected to be encoded in
60 \dd In read mode, causes \cw{xcopy} to request the selection using
61 the type \cw{UTF8_STRING}, which typically means that the returned
62 data will be encoded as UTF-8. In write mode, causes \cw{xcopy} to
63 \e{give out} the selection as type \cw{UTF8_STRING}, meaning that
64 the data piped in to it is expected to be encoded as UTF-8.
68 \dd Similar to \cw{-u}, but uses the type \cw{COMPOUND_TEXT} rather
69 than \cw{UTF8_STRING}. \cw{COMPOUND_TEXT} is a complex
70 multi-character-set encoding similar to ISO 2022, and is unlikely to
71 be a very useful form in which to pass data to or from non-X
72 programs. However, it might occasionally be useful to retrieve a
73 compound text selection using \cw{xcopy -r -c}, and later on return
74 it to the X selection using \cw{xcopy -c} so it can be pasted back
75 into a different application.
77 In write mode, if \cw{xcopy} is operating in \cw{STRING} mode and a
78 pasting application requests the selection as \cw{COMPOUND_TEXT},
79 \cw{xcopy} will convert the data automatically. This is normally
84 \dd Suppresses conversion to compound text in write mode. This is
85 occasionally useful if you are pasting control characters, since the
86 compound text specification forbids any control characters and the
87 Xlib conversion functions honour this. If you are (for example)
88 trying to paste a sequence of editor commands into a terminal
89 window, you might well want to paste a string full of escape
90 sequences and control characters, in which case you may need to use
91 \cw{-C} to disable conversion to compound text.
95 \dd Causes \cw{xcopy} to read or write the clipboard instead of the
96 selection. (Modern GNOME and KDE-style programs can often interact
97 with both. The \e{selection} is the traditional X-style storage
98 location which you typically copy things into just by selecting them
99 with the mouse, and paste with the middle mouse button. The
100 \e{clipboard} is a more Windows-like location which you access using
101 explicit Cut, Copy and Paste commands in your application.)
105 Occasionally \cw{xcopy -r} completely fails to notice selection data
106 owned by another process. I have not yet reproduced this reliably;
107 if anyone can, some work with \cw{xmon}(1) would be much
110 Automatic conversion between compound text and UTF-8 is not
111 currently supported. There are Xlib functions to do it, although
112 they don't appear to work very well (missing out many characters
113 which they could have converted).
117 \cw{xcopy} is free software, distributed under the MIT licence. Type
118 \cw{xcopy --licence} to see the full licence text.