mdw@git.distorted.org.uk Git - sgt/utils/blob - xcopy/xcopy.but

   1 \cfg{man-identity}{xcopy}{1}{2004-08-02}{Simon Tatham}{Simon Tatham}
   2
   3 \title Man page for \cw{xcopy}
   4
   5 \U NAME
   6
   7 \cw{xcopy} - read and write text to/from an X selection from the
   8 command line
   9
  10 \U SYNOPSIS
  11
  12 \c xcopy [ -r ] [ -u | -c ] [ -C ]
  13 \e bbbbb   bb     bb   bb     bb
  14
  15 \U DESCRIPTION
  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
  44 \U OPTIONS
  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
  93 \dt \cw{-b}
  94
  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.)
 102
 103 \dt \cw{-t}
 104
 105 \dd Causes \cw{xcopy}, in read mode only, to return the list of
 106 possible target types currently stored in the selection. This is
 107 probably only useful for debugging X applications or X selection
 108 issues.
 109
 110 \dt \cw{-T}
 111
 112 \dd Causes \cw{xcopy}, in read mode only, to return the time stamp
 113 for the current selection. This is probably only useful for
 114 debugging X applications or X selection issues.
 115
 116 \dt \cw{-a} \e{target atom}
 117
 118 \dd Causes \cw{xcopy}, in read mode only, to return the selection
 119 contents corresponding to some particular user-specified target
 120 type. The target type can be anything listed by \cq{xcopy -r -t}.
 121
 122 \U BUGS
 123
 124 Occasionally \cw{xcopy -r} completely fails to notice selection data
 125 owned by another process. I have not yet reproduced this reliably;
 126 if anyone can, some work with \cw{xmon}(1) would be much
 127 appreciated...
 128
 129 Automatic conversion between compound text and UTF-8 is not
 130 currently supported. There are Xlib functions to do it, although
 131 they don't appear to work very well (missing out many characters
 132 which they could have converted).
 133
 134 \U LICENCE
 135
 136 \cw{xcopy} is free software, distributed under the MIT licence. Type
 137 \cw{xcopy --licence} to see the full licence text.
 138
 139 \versionid $Id$