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 \dt \cw{-v}
 123
 124 \dd Causes \cw{xcopy}, in read mode only, to produce a verbose
 125 commentary on the progress of reading the X selection. Can be useful
 126 for debugging interactions with other programs.
 127
 128 \dt \cw{-F}
 129
 130 \dd Causes \cw{xcopy} not to fork, when in write mode. Instead the
 131 original \cw{xcopy} process will continue to run until the selection
 132 is taken away from it. Probably only useful when debugging
 133 \cw{xcopy} itself, although it's just possible that it might turn
 134 out to be useful for some other special purpose (e.g. having the
 135 process waiting for it know when the selection owner has changed).
 136
 137 \dt \cw{-d} \e{size}
 138
 139 \dd Alters the maximum size of data transferred in one lump by
 140 \cw{xcopy}. (Probably most useful for diagnostic purposes.)
 141
 142 \dt \cw{-I}
 143
 144 \dd Inhibits \cw{xcopy}, in write mode, from using the \cw{INCR}
 145 mechanism for transferring large amounts of selection data a piece at
 146 a time and waiting for the recipient to acknowledge each chunk before
 147 sending the next. (Just in case a client doesn't support it.)
 148
 149 \dt \cw{-B}
 150
 151 \dd Inhibits \cw{xcopy}, in write mode, from storing its data in the
 152 persistent \q{cut buffers} on the root window as well as using the
 153 peer-to-peer selection mechanism.
 154
 155 \U BUGS
 156
 157 Automatic conversion between compound text and UTF-8 is not
 158 currently supported. There are Xlib functions to do it, although
 159 they don't appear to work very well (missing out many characters
 160 which they could have converted).
 161
 162 \U LICENCE
 163
 164 \cw{xcopy} is free software, distributed under the MIT licence. Type
 165 \cw{xcopy --licence} to see the full licence text.
 166
 167 \versionid $Id$