Man page for xcopy

NAME

xcopy – read and write text to/from an X selection from the command line

SYNOPSIS

xcopy [ -r ] [ -u | -c ] [ -C ]

DESCRIPTION

xcopy is a command-line utility for manipulating the X selection.

It has two basic modes. In read mode (xcopy -r), it connects to your X server, retrieves the contents of the selection as plain text, and writes it on standard output. You would then typically redirect its output into a file, or pipe it into some other program.

In write mode (just xcopy, if -r is not specified), it will read data from standard input, then connect to your X server and place that data in the selection as plain text. So you can pipe data into xcopy, move to another application, and press Paste.

The X selection model requires the selection-owning client to remain connected to the server and hand out its data on request. Therefore, xcopy in write mode forks off a background process which does this. The background process terminates once it is no longer the selection owner (i.e. as soon as you select data in another application), or if your X session finishes. Normally you can ignore its presence, although it might become important to be aware of it if (for example) the xcopy background process were to be the last X client still connected through an SSH tunnel.

xcopy currently only handles text data. However, it is capable of handling it in the form of plain text, UTF-8, or compound (multiple-character-set) text. Use the -u, -c and -C options to control this aspect of its behaviour.

Finally, xcopy can also support the source end of the Xdnd protocol for drag and drop (since it's closely related to selections). Use -D with a file name to drop the full pathname of that file into an application that accepts pathname drops, such as web browsers that let you attach files to upload forms, or mail clients that let you drag files into a mail composer window to use as attachments. The mouse pointer will become a crosshair, and you should click it in a window where you want to drop the file. Alternatively, use the --drop option to manually set up a drag-and-drop of some other kind of data.

OPTIONS

By default (if -r is not supplied), xcopy operates in write mode.

-r

Places xcopy into read mode.

By default (if neither -c nor -u is supplied), xcopy reads and writes the selection using the type STRING, which means that the input or output data is expected to be encoded in ISO-8859-1.

-u

In read mode, causes xcopy to request the selection using the type UTF8_STRING, which typically means that the returned data will be encoded as UTF-8. In write mode, causes xcopy to give out the selection as type UTF8_STRING, meaning that the data piped in to it is expected to be encoded as UTF-8.

-c

Similar to -u, but uses the type COMPOUND_TEXT rather than UTF8_STRING. COMPOUND_TEXT is a complex multi-character-set encoding similar to ISO 2022, and is unlikely to be a very useful form in which to pass data to or from non-X programs. However, it might occasionally be useful to retrieve a compound text selection using xcopy -r -c, and later on return it to the X selection using xcopy -c so it can be pasted back into a different application.

In write mode, if xcopy is operating in STRING mode and a pasting application requests the selection as COMPOUND_TEXT, xcopy will convert the data automatically. This is normally what you want.

-C

Suppresses conversion to compound text in write mode. This is occasionally useful if you are pasting control characters, since the compound text specification forbids any control characters and the Xlib conversion functions honour this. If you are (for example) trying to paste a sequence of editor commands into a terminal window, you might well want to paste a string full of escape sequences and control characters, in which case you may need to use -C to disable conversion to compound text.

-h, -H

Like -u and -c, these two options change the type of the selection data. This time, they set it to the string ‘text/html’, which is a selection format used by at least Firefox when you select or copy text on a web page.

-H retrieves the ‘text/html’ selection data in its raw format, which is encoded in UTF-16. -h automatically converts between that and UTF-8, which is generally more useful in a mostly UTF-8 oriented world.

-b

Causes xcopy to read or write the clipboard instead of the selection. (Modern GNOME and KDE-style programs can often interact with both. The selection is the traditional X-style storage location which you typically copy things into just by selecting them with the mouse, and paste with the middle mouse button. The clipboard is a more Windows-like location which you access using explicit Cut, Copy and Paste commands in your application.)

-t

Causes xcopy, in read mode only, to return the list of possible target types currently stored in the selection. This is probably only useful for debugging X applications or X selection issues.

-T

Causes xcopy, in read mode only, to return the time stamp for the current selection. This is probably only useful for debugging X applications or X selection issues.

-a target atom

Causes xcopy to request (in read mode) or announce (in write mode) the selection contents with a user-specified target data type. For read mode, the target type can be anything listed by ‘xcopy -r -t’. For write mode, you can choose anything you think the pasting application will support.

-v

Causes xcopy, in read mode only, to produce a verbose commentary on the progress of reading the X selection. Can be useful for debugging interactions with other programs.

-F

Causes xcopy not to fork, when in write mode. Instead the original xcopy process will continue to run until the selection is taken away from it. Probably only useful when debugging xcopy itself, although it's just possible that it might turn out to be useful for some other special purpose (e.g. having the process waiting for it know when the selection owner has changed).

-d size

Alters the maximum size of data transferred in one lump by xcopy. (Probably most useful for diagnostic purposes.)

-I

Inhibits xcopy, in write mode, from using the INCR mechanism for transferring large amounts of selection data a piece at a time and waiting for the recipient to acknowledge each chunk before sending the next. (Just in case a client doesn't support it.)

-B

Inhibits xcopy, in write mode, from storing its data in the persistent ‘cut buffers’ on the root window as well as using the peer-to-peer selection mechanism.

-D filename

Puts xcopy into drag-and-drop mode. xcopy will take control of the mouse pointer, similar to the way xwininfo(1) or xprop(1) does, and allow you to click on an application to receive the dragged-and-dropped data. Click the left button over an eligible receiving window to drop data there; click the middle or right button to cancel the drop and terminate xcopy.

The data in question will be a text/uri-list consisting of a file:// URI identifying the full local pathname of the file you specify. This allows you to conveniently drag and drop a file from wherever your shell's cwd is.

--drop

Also enters drag-and-drop mode, but allows you to drop data of whatever type you choose. With this option, the data is piped into xcopy's standard input, just as if it were being placed in a selection (which it is, in fact – that's how the Xdnd protocol works).

BUGS

Automatic conversion between compound text and UTF-8 is not currently supported. There are Xlib functions to do it, although they don't appear to work very well (missing out many characters which they could have converted).

LICENCE

xcopy is free software, distributed under the MIT licence. Type xcopy --licence to see the full licence text.