File: multitee.1

package info (click to toggle)
multitee 3.0-5
  • links: PTS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 232 kB
  • ctags: 375
  • sloc: ansic: 1,673; makefile: 7
file content (174 lines) | stat: -rw-r--r-- 3,752 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
.TH multitee 1
.SH NAME
multitee \- send multiple inputs to multiple outputs
.SH SYNTAX
multitee
[
\fB\-b\fIsize
] [
\fB\-vQq\fI
] [
\fIfd-fd,fd,fd...
] ...
.SH DESCRIPTION
.B multitee
sends multiple inputs to multiple outputs.
Given an argument of the form
.I fdin-fdout,fdout,fdout...
it will send all input on file descriptor
.I fdin
to each descriptor
.I fdout.
It will exit when all
.I fdin
are closed.
Several arguments may specify outputs from the same
.I fdin.

.I -fdout
and
.I ,fdout
are equivalent.
If there is an error of any sort (including SIGPIPE) in writing to
.I fdout,
.B multitee
prints a warning on stderr
and forgets
.I fdout
entirely.
(This doesn't affect reads on
.I fdin.)
If
.I -fdout
is replaced by
.I :fdout
then
.B multitee
will exit upon any SIGPIPEs from that descriptor.

Furthermore,
.I \fBe\fIfd
means that as soon as
.I fdin
reaches end of file,
.I fd
is considered to reach EOF as well.
.B multitee
will warn about any
input errors
and then treat them like EOF.

Unlike
.I tee,
.B multitee
tries its best to continue processing all descriptors even while
some of them are blocked. However, it will get stuck reading if
someone else is reading the descriptor and grabs the input first;
it will get stuck writing if an input packet does not fit in an
output pipe.
(If the output descriptor has NDELAY set,
and
.B multitee
receives EWOULDBLOCK,
it writes one byte at a time to avoid pipe synchronization problems.)
While it is tempting to set the descriptors to non-blocking mode,
this is dangerous: other processes using the same open file may not be
able to deal with NDELAY.
It is incredible that none of the major UNIX vendors or standards
committees has come up with true per-process non-blocking I/O.
(Under BSD 4.3 and its variants, multitee could send timer signals
to itself rapidly to interrupt any blocking I/O. However, this cannot
work under BSD 4.2, and is generally more trouble than it's worth.)
A program can set NDELAY before invoking
.B multitee
if it
knows that no other processes will use the same open file.

.B multitee
will also temporarily stop reading an input descriptor if
more than 8192 bytes are pending on one of its output
descriptors. This does not affect independent
.I fdin-fdout
pairs.

.B multitee
has several flags:
.TP 12
\fB\-b\fIsize
Change input buffer size from 8192 to
.I size.
Unlike the previous version of
.B multitee,
this version does not require output buffers,
and does not copy bytes anywhere between
read() and write().
.TP
\fB\-v\fI
Verbose.
.TP
\fB\-q\fI
Quiet.
.B multitee
will not use stderr in any way
(except, of course, if descriptor 2 is
specified in an argument).
.TP
\fB\-Q\fI
Normal level of verbosity.
.PP
.SH "EXIT VALUE"
0 normally.
1 for usage messages.
3 if
.B multitee
runs out of memory.
4 in various impossible situations.
.SH DIAGNOSTICS
.TP
.I fatal: out of memory
.B multitee
has run out of memory.
.TP
.I warning: cannot read descriptor
Self-explanatory.
.TP
.I warning: cannot write descriptor
Self-explanatory.
.SH EXAMPLES
.EX
multitee 0-1,4,5 4>foo 5>bar
.EE
.PP
Same as
.I tee foo bar
except for better blocking behavior.
.PP
.EX
multitee 0:1 3:1 4:1,2 6:7
.EE
.PP
Merge several sources into the output,
meanwhile copying 6 to 7
and recording 4's input in 2.
.PP
.EX
tcpclient servermachine smtp multitee 0:7 6:1e0
.EE
.PP
Same as
.I mconnect
on Suns.
The e0 tells multitee to quit as soon as the network connection closes.
.SH RESTRICTIONS
.B multitee
expects all descriptors involved to be open.
Currently a closed descriptor acts like an open
descriptor which can never be written to.
.SH BUGS
None known.
.SH VERSION
multitee version 3.0, 7/22/91.
.SH AUTHOR
Placed into the public domain by Daniel J. Bernstein.
.SH "SEE ALSO"
tee(1)