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 \define{dash} \u2013{-}
   4
   5 \title Man page for \cw{xcopy}
   6
   7 \U NAME
   8
   9 \cw{xcopy} \dash read and write text to/from an X selection from the
  10 command line
  11
  12 \U SYNOPSIS
  13
  14 \c xcopy [ -r ] [ -u | -c ] [ -C ]
  15 \e bbbbb   bb     bb   bb     bb
  16
  17 \U DESCRIPTION
  18
  19 \cw{xcopy} is a command-line utility for manipulating the X selection.
  20
  21 It has two basic modes. In read mode (\cw{xcopy -r}), it connects to
  22 your X server, retrieves the contents of the selection as plain
  23 text, and writes it on standard output. You would then typically
  24 redirect its output into a file, or pipe it into some other program.
  25
  26 In write mode (just \cw{xcopy}, if \cw{-r} is not specified), it
  27 will read data from standard input, then connect to your X server
  28 and place that data in the selection as plain text. So you can pipe
  29 data into \cw{xcopy}, move to another application, and press Paste.
  30
  31 The X selection model requires the selection-owning client to remain
  32 connected to the server and hand out its data on request. Therefore,
  33 \cw{xcopy} in write mode forks off a background process which does
  34 this. The background process terminates once it is no longer the
  35 selection owner (i.e. as soon as you select data in another
  36 application), or if your X session finishes. Normally you can ignore
  37 its presence, although it might become important to be aware of it
  38 if (for example) the \cw{xcopy} background process were to be the
  39 last X client still connected through an SSH tunnel.
  40
  41 \cw{xcopy} currently only handles text data. However, it is capable
  42 of handling it in the form of plain text, UTF-8, or compound
  43 (multiple-character-set) text. Use the \cw{-u}, \cw{-c} and \cw{-C}
  44 options to control this aspect of its behaviour.
  45
  46 \U OPTIONS
  47
  48 By default (if \cw{-r} is not supplied), \cw{xcopy} operates in
  49 write mode.
  50
  51 \dt \cw{-r}
  52
  53 \dd Places \cw{xcopy} into read mode.
  54
  55 By default (if neither \cw{-c} nor \cw{-u} is supplied), \cw{xcopy}
  56 reads and writes the selection using the type \cw{STRING}, which
  57 means that the input or output data is expected to be encoded in
  58 ISO-8859-1.
  59
  60 \dt \cw{-u}
  61
  62 \dd In read mode, causes \cw{xcopy} to request the selection using
  63 the type \cw{UTF8_STRING}, which typically means that the returned
  64 data will be encoded as UTF-8. In write mode, causes \cw{xcopy} to
  65 \e{give out} the selection as type \cw{UTF8_STRING}, meaning that
  66 the data piped in to it is expected to be encoded as UTF-8.
  67
  68 \dt \cw{-c}
  69
  70 \dd Similar to \cw{-u}, but uses the type \cw{COMPOUND_TEXT} rather
  71 than \cw{UTF8_STRING}. \cw{COMPOUND_TEXT} is a complex
  72 multi-character-set encoding similar to ISO 2022, and is unlikely to
  73 be a very useful form in which to pass data to or from non-X
  74 programs. However, it might occasionally be useful to retrieve a
  75 compound text selection using \cw{xcopy -r -c}, and later on return
  76 it to the X selection using \cw{xcopy -c} so it can be pasted back
  77 into a different application.
  78
  79 In write mode, if \cw{xcopy} is operating in \cw{STRING} mode and a
  80 pasting application requests the selection as \cw{COMPOUND_TEXT},
  81 \cw{xcopy} will convert the data automatically. This is normally
  82 what you want.
  83
  84 \dt \cw{-C}
  85
  86 \dd Suppresses conversion to compound text in write mode. This is
  87 occasionally useful if you are pasting control characters, since the
  88 compound text specification forbids any control characters and the
  89 Xlib conversion functions honour this. If you are (for example)
  90 trying to paste a sequence of editor commands into a terminal
  91 window, you might well want to paste a string full of escape
  92 sequences and control characters, in which case you may need to use
  93 \cw{-C} to disable conversion to compound text.
  94
  95 \dt \cw{-b}
  96
  97 \dd Causes \cw{xcopy} to read or write the clipboard instead of the
  98 selection. (Modern GNOME and KDE-style programs can often interact
  99 with both. The \e{selection} is the traditional X-style storage
 100 location which you typically copy things into just by selecting them
 101 with the mouse, and paste with the middle mouse button. The
 102 \e{clipboard} is a more Windows-like location which you access using
 103 explicit Cut, Copy and Paste commands in your application.)
 104
 105 \dt \cw{-t}
 106
 107 \dd Causes \cw{xcopy}, in read mode only, to return the list of
 108 possible target types currently stored in the selection. This is
 109 probably only useful for debugging X applications or X selection
 110 issues.
 111
 112 \dt \cw{-T}
 113
 114 \dd Causes \cw{xcopy}, in read mode only, to return the time stamp
 115 for the current selection. This is probably only useful for
 116 debugging X applications or X selection issues.
 117
 118 \dt \cw{-a} \e{target atom}
 119
 120 \dd Causes \cw{xcopy}, in read mode only, to return the selection
 121 contents corresponding to some particular user-specified target
 122 type. The target type can be anything listed by \cq{xcopy -r -t}.
 123
 124 \dt \cw{-v}
 125
 126 \dd Causes \cw{xcopy}, in read mode only, to produce a verbose
 127 commentary on the progress of reading the X selection. Can be useful
 128 for debugging interactions with other programs.
 129
 130 \dt \cw{-F}
 131
 132 \dd Causes \cw{xcopy} not to fork, when in write mode. Instead the
 133 original \cw{xcopy} process will continue to run until the selection
 134 is taken away from it. Probably only useful when debugging
 135 \cw{xcopy} itself, although it's just possible that it might turn
 136 out to be useful for some other special purpose (e.g. having the
 137 process waiting for it know when the selection owner has changed).
 138
 139 \dt \cw{-d} \e{size}
 140
 141 \dd Alters the maximum size of data transferred in one lump by
 142 \cw{xcopy}. (Probably most useful for diagnostic purposes.)
 143
 144 \dt \cw{-I}
 145
 146 \dd Inhibits \cw{xcopy}, in write mode, from using the \cw{INCR}
 147 mechanism for transferring large amounts of selection data a piece at
 148 a time and waiting for the recipient to acknowledge each chunk before
 149 sending the next. (Just in case a client doesn't support it.)
 150
 151 \dt \cw{-B}
 152
 153 \dd Inhibits \cw{xcopy}, in write mode, from storing its data in the
 154 persistent \q{cut buffers} on the root window as well as using the
 155 peer-to-peer selection mechanism.
 156
 157 \U BUGS
 158
 159 Automatic conversion between compound text and UTF-8 is not
 160 currently supported. There are Xlib functions to do it, although
 161 they don't appear to work very well (missing out many characters
 162 which they could have converted).
 163
 164 \U LICENCE
 165
 166 \cw{xcopy} is free software, distributed under the MIT licence. Type
 167 \cw{xcopy --licence} to see the full licence text.
 168
 169 \versionid $Id$