9acadc2b |
1 | \cfg{man-identity}{xcopy}{1}{2004-08-02}{Simon Tatham}{Simon Tatham} |
9acadc2b |
2 | |
8a48d402 |
3 | \title Man page for \cw{xcopy} |
9acadc2b |
4 | |
8a48d402 |
5 | \U NAME |
9acadc2b |
6 | |
7 | \cw{xcopy} - read and write text to/from an X selection from the |
8 | command line |
9 | |
8a48d402 |
10 | \U SYNOPSIS |
9acadc2b |
11 | |
12 | \c xcopy [ -r ] [ -u | -c ] [ -C ] |
13 | \e bbbbb bb bb bb bb |
14 | |
8a48d402 |
15 | \U DESCRIPTION |
9acadc2b |
16 | |
17 | \cw{xcopy} is a command-line utility for manipulating the X selection. |
18 | |
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. |
23 | |
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. |
28 | |
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. |
38 | |
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. |
43 | |
8a48d402 |
44 | \U OPTIONS |
9acadc2b |
45 | |
46 | By default (if \cw{-r} is not supplied), \cw{xcopy} operates in |
47 | write mode. |
48 | |
49 | \dt \cw{-r} |
50 | |
51 | \dd Places \cw{xcopy} into read mode. |
52 | |
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 |
56 | ISO-8859-1. |
57 | |
58 | \dt \cw{-u} |
59 | |
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. |
65 | |
66 | \dt \cw{-c} |
67 | |
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. |
76 | |
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 |
80 | what you want. |
81 | |
82 | \dt \cw{-C} |
83 | |
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. |
92 | |
8a48d402 |
93 | \U BUGS |
9acadc2b |
94 | |
95 | Occasionally \cw{xcopy -r} completely fails to notice selection data |
96 | owned by another process. I have not yet reproduced this reliably; |
97 | if anyone can, some work with \cw{xmon}(1) would be much |
98 | appreciated... |
99 | |
100 | Automatic conversion between compound text and UTF-8 is not |
101 | currently supported. There are Xlib functions to do it, although |
102 | they don't appear to work very well (missing out many characters |
103 | which they could have converted). |
da0f8522 |
104 | |
8a48d402 |
105 | \U LICENCE |
da0f8522 |
106 | |
107 | \cw{xcopy} is free software, distributed under the MIT licence. Type |
108 | \cw{xcopy --licence} to see the full licence text. |
1166ff62 |
109 | |
110 | \versionid $Id$ |