src/parcat.pod

   1 #!/usr/bin/perl
   2
   3 # SPDX-FileCopyrightText: 2021-2024 Ole Tange, http://ole.tange.dk and Free Software and Foundation, Inc.
   4 # SPDX-License-Identifier: GFDL-1.3-or-later
   5 # SPDX-License-Identifier: CC-BY-SA-4.0
   6
   7 =head1 NAME
   8
   9 parcat - cat files or fifos in parallel
  10
  11 =head1 SYNOPSIS
  12
  13 B<parcat> [--rm] [-#] file(s) [-#] file(s)
  14
  15 =head1 DESCRIPTION
  16
  17 GNU B<parcat> reads files or fifos in parallel. It writes full lines
  18 so there will be no problem with mixed-half-lines which you risk if
  19 you use:
  20
  21    (cat file1 & cat file2 &) | ...
  22
  23 It is faster than doing:
  24
  25    parallel -j0 --lb cat ::: file*
  26
  27 Arguments can be given on the command line or passed in on stdin
  28 (standard input).
  29
  30 =head1 OPTIONS
  31
  32 =over 9
  33
  34 =item -B<#>
  35
  36 Arguments following this will be sent to the file descriptor B<#>. E.g.
  37
  38   parcat -1 stdout1 stdout2 -2 stderr1 stderr2
  39
  40 will send I<stdout1> and I<stdout2> to stdout (standard output = file
  41 descriptor 1), and send I<stderr1> and I<stderr2> to stderr (standard
  42 error = file descriptor 2).
  43
  44 =item --rm
  45
  46 Remove files after opening. As soon as the files are opened, unlink
  47 the files.
  48
  49 =back
  50
  51 =head1 EXAMPLES
  52
  53 =head2 Simple line buffered output
  54
  55 B<traceroute> will often print half a line. If run in parallel, two
  56 instances may half-lines of their output. This can be avoided by
  57 saving the output to a fifo and then using B<parcat> to read the two
  58 fifos in parallel:
  59
  60   mkfifo freenetproject.org.fifo tange.dk.fifo
  61   traceroute freenetproject.org > freenetproject.org.fifo &
  62   traceroute tange.dk > tange.dk.fifo &
  63   parcat --rm *fifo
  64
  65
  66 =head1 REPORTING BUGS
  67
  68 GNU B<parcat> is part of GNU B<parallel>. Report bugs to
  69 <bug-parallel@gnu.org>.
  70
  71
  72 =head1 AUTHOR
  73
  74 Copyright (C) 2016-2024 Ole Tange, http://ole.tange.dk and Free
  75 Software Foundation, Inc.
  76
  77 =head1 LICENSE
  78
  79 This program is free software; you can redistribute it and/or modify
  80 it under the terms of the GNU General Public License as published by
  81 the Free Software Foundation; either version 3 of the License, or
  82 at your option any later version.
  83
  84 This program is distributed in the hope that it will be useful,
  85 but WITHOUT ANY WARRANTY; without even the implied warranty of
  86 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  87 GNU General Public License for more details.
  88
  89 You should have received a copy of the GNU General Public License
  90 along with this program.  If not, see <http://www.gnu.org/licenses/>.
  91
  92 =head2 Documentation license I
  93
  94 Permission is granted to copy, distribute and/or modify this
  95 documentation under the terms of the GNU Free Documentation License,
  96 Version 1.3 or any later version published by the Free Software
  97 Foundation; with no Invariant Sections, with no Front-Cover Texts, and
  98 with no Back-Cover Texts.  A copy of the license is included in the
  99 file LICENSES/GFDL-1.3-or-later.txt.
 100
 101 =head2 Documentation license II
 102
 103 You are free:
 104
 105 =over 9
 106
 107 =item B<to Share>
 108
 109 to copy, distribute and transmit the work
 110
 111 =item B<to Remix>
 112
 113 to adapt the work
 114
 115 =back
 116
 117 Under the following conditions:
 118
 119 =over 9
 120
 121 =item B<Attribution>
 122
 123 You must attribute the work in the manner specified by the author or
 124 licensor (but not in any way that suggests that they endorse you or
 125 your use of the work).
 126
 127 =item B<Share Alike>
 128
 129 If you alter, transform, or build upon this work, you may distribute
 130 the resulting work only under the same, similar or a compatible
 131 license.
 132
 133 =back
 134
 135 With the understanding that:
 136
 137 =over 9
 138
 139 =item B<Waiver>
 140
 141 Any of the above conditions can be waived if you get permission from
 142 the copyright holder.
 143
 144 =item B<Public Domain>
 145
 146 Where the work or any of its elements is in the public domain under
 147 applicable law, that status is in no way affected by the license.
 148
 149 =item B<Other Rights>
 150
 151 In no way are any of the following rights affected by the license:
 152
 153 =over 9
 154
 155 =item *
 156
 157 Your fair dealing or fair use rights, or other applicable
 158 copyright exceptions and limitations;
 159
 160 =item *
 161
 162 The author's moral rights;
 163
 164 =item *
 165
 166 Rights other persons may have either in the work itself or in
 167 how the work is used, such as publicity or privacy rights.
 168
 169 =back
 170
 171 =item B<Notice>
 172
 173 For any reuse or distribution, you must make clear to others the
 174 license terms of this work.
 175
 176 =back
 177
 178 A copy of the full license is included in the file as
 179 LICENCES/CC-BY-SA-4.0.txt
 180
 181
 182 =head1 DEPENDENCIES
 183
 184 GNU B<parcat> uses Perl.
 185
 186
 187 =head1 SEE ALSO
 188
 189 B<cat>(1), B<parallel>(1)
 190
 191 =cut