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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Redirector)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
(System Level File Redirection)
manpagename(FBB::Redirector)(Redirects a file descriptor to another descriptor)
manpagesynopsis()
bf(#include <bobcat/redirector>)nl()
Linking option: tt(-lbobcat)
manpagedescription()
Objects of the class bf(FBB::Redirector) set up a system level file
redirection, using file descriptors rather than streams. tt(Redirector)
objects are effectively em(wrappers) around the bf(dup2)(2) system
call. System level redirection allows the programmer to send output to, e.g.,
the standard output stream, which actually appears at another stream (e.g.,
the standard error).
tt(Redirector) objects are used to redirect the output sent to a stream
having file descriptor tt(x) to another stream having file descriptor tt(y),
much like the shell's tt(>) operator redirects the standard output to some
file.
tt(Redirector) objects can also be used to extract the information from a
stream having file descriptor tt(x) in fact from another stream having file
descriptor tt(y), much like the shell's tt(<) operator is used to read the
information in some file from the standard input.
Redirection using tt(Redirector) objects represents a stronger form of
redirection than redirection offered by bf(C++) itself, which uses
tt(std::streambuf) redirection, and which is, because of that, bound to the
program's scope. System level redirection, on the other hand, is applied at
the system level, allowing the programmer to redirect standard streams when
starting a program. For example, the standard error is commonly written to the
standard output using an invocation like tt(program 2>&1).
When constructing tt(Redirector) objects a file descriptor is
required. The file descriptor specified at the constructor is the file
descriptor that is used by the program to read information from or to write
information to. Another file descriptor is required to set up the
redirection: the file descriptor used here is the file descriptor of the
stream that actually holds the information which is extracted from the file
descriptor that was passed to the tt(Redirector)'s constructor; or it is the
file descriptor of the stream receiving the information which is written to
the stream having the file descriptor that was passed to the tt(Redirector)'s
constructor.
When a tt(Redirector) object goes out of scope, its file descriptor are
left as-is. In particular, note that no bf(close)(2) operation is performed on
the tt(Redirector's) file descriptors. After setting up redirection using the
tt(Redirector's) member functions and passing the tt(Redirector's) file
descriptors to code that uses the tt(Redirector's) descriptors, the
tt(Redirector) object could in fact safely be destroyed.
Formally, file descriptors are not defined in bf(C++), but they are
available in many types of operating systems. In those systems each `file' has
an associated `file descriptor'. A file descriptor is an bf(int), which is an
index into the program's file allocation table, maintained by the
system. Another type of well-known entities which are file descriptors are
em(sockets).
Well-known filedescriptors (defined in, e.g., tt(unistd.h))
having fixed values are
itemization(
tt() 0 (tt(STDIN_FILENO)), representing the standard input stream
(tt(std::cin));
tt() 1, (tt(STDOUT_FILENO)), representing the standard output stream
(tt(std::cout));
tt() 2, (tt(STDERR_FILENO)), representing the standard error stream
(tt(cerr));
)
Notes:
itemization(
it() System-level redirections are kept during system calls of the
bf(exec)(3) family.
it() Destroying a tt(Redirector) object does em(not) undo the
redirection set up by that object.
)
includefile(include/namespace)
manpagesection(INHERITS FROM)
-
manpagesection(ENUM)
The enumeration bf(StandardFileno) holds the following values:
itemization(
itt(STDIN) (0)
itt(STDOUT) (1)
itt(STDERR) (2)
)
These values may be used to set up a redirection instead of the plain
numbers.
manpagesection(CONSTRUCTORS)
itemization(
itb(Redirector(int fd))
This constructor expects the file descriptor of the file that will be
used by the program to access (read, write) another file. The file descriptor
that is passed to the constructor is used by the program, and will often be
tt(STDIN, STDOUT), or tt(STDERR), allowing the program to use tt(cin, cout),
or tt(cerr) to extract information from, or insert information into other
streams using its standard input and output streams.
)
Copy and move constructors (and assignment operators) are available.
manpagesection(MEMBER FUNCTIONS)
itemization(
itb(void swallow(int otherFd) const)
This member function expects a file descriptor which should become a
synonym of the constructor's file descriptor. The constructor's file
descriptor is redirected to tt(otherFd).
After successfully calling tt(swallow) information written to
tt(otherFd) is in fact written to the constructor's file descriptor. E.g., if
the constructor's file descriptor represents a file on disk and tt(otherFd) is
tt(STDOUT_FILENO) then all information sent to the standard output stream is
actually sent to the file on disk:
verb(
information sent to otherFd -> is received at the constructor's Fd
(e.g., otherFd = STDOUT_FILENO)
)
Conversely, if the constructor's file descriptor represents a file on
disk and tt(otherFd) is tt(STDIN_FILENO) then all information extracted from
the standard input stream is actually read from the file on disk.
verb(
information extracted from otherFd <- is read from the constructor's Fd
(e.g., otherFd = STDIN_FILENO)
)
Following tt(swallow) both file descriptors
are open, and refer to the constructor's file descriptor.
Before setting up the redirection, the original tt(otherFd) is closed
by bf(close)(2). Following tt(swallow) both file descriptors can be used, and
refer to the constructor's file descriptor. If after calling tt(swallow)
bf(close)(2) is called for one of them, then the other one remains open.
If redirection fails an bf(FBB::Exception) object is thrown, whose
tt(which()) member shows the system's tt(errno) value set by the failing
bf(dup2)(2) function.
itb(void through(int otherFd) const)
This member function expects a file descriptor which should become a
synonym of the constructor's file descriptor. The constructor's file
descriptor is redirected to tt(otherFd). The constructor's file descriptor can
no longer be used, as it is closed by bf(close)(2).
After successfully calling tt(through) information written to
tt(otherFd) is in fact written to the constructor's file descriptor. E.g., if
the constructor's file descriptor represents a file on disk and tt(otherFd) is
tt(STDOUT_FILENO) then all information sent to the standard output stream is
actually sent to the file on disk:
verb(
information sent to otherFd -> is received at the constructor's Fd
(e.g., otherFd = STDOUT_FILENO)
)
Conversely, if the constructor's file descriptor represents a file on
disk and tt(otherFd) is tt(STDIN_FILENO) then all information extracted from
the standard input stream is actually read from the file on disk.
verb(
information extracted from otherFd <- is read from the constructor's Fd
(e.g., otherFd = STDIN_FILENO)
)
Before setting up the redirection, the original tt(otherFd) is closed
by bf(close)(2). Following tt(through) only tt(otherFd) can be used, and
it refers to (i.e., reads or writes) the constructor's file descriptor.
If redirection fails an bf(FBB::Exception) object is thrown, whose
tt(which()) member shows the system's tt(errno) value set by the failing
bf(dup2)(2) function.
)
manpagesection(EXAMPLE)
verb(
#include <iostream>
#include <bobcat/redirector>
using namespace std;
using namespace FBB;
int main()
{
Redirector redirector(Redirector::STDOUT);
redirector.swallow(Redirector::STDERR);
cerr << "This appears at the standard output stream\n"
"use `a.out > /dev/null' to suppress this message" << endl;
}
)
manpagefiles()
em(bobcat/redirector) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(dup2)(2), bf(execl)(3)
manpagebugs()
None Reported.
includefile(include/trailer)
|
