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
|
.\"
.\" libexplain - Explain errno values returned by libc functions
.\" Copyright (C) 2009, 2011 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or (at
.\" your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.ds n) explain_pclose_or_die
.cp 0 \" Solaris defaults to ''.cp 1'', sheesh.
.TH explain_pclose_or_die 3
.SH NAME
explain_pclose_or_die \- process I/O and report errors
.if require_index \{
.XX "explain_pclose_or_die(3)" \
"process I/O and report errors"
.\}
.SH SYNOPSIS
#include <libexplain/pclose.h>
.sp 0.3
int explain_pclose_or_die(FILE *fp);
.br
int explain_pclose_success(FILE *fp);
.br
void explain_pclose_success_or_die(FILE *fp);
.SH DESCRIPTION
These functions may be used to wait for program termination,
and then reprt errors returned by the \f[I]pclose\fP(3) system call.
.\" ----------------------------------------------------
.SS explain_pclose_or_die
int explain_pclose_or_die(FILE *fp);
.PP
The \f[B]explain_pclose_or_die\fP function
is used to call the \f[I]pclose\fP(3) system
call. On failure an explanation will be
printed to \f[I]stderr\fP,
obtained from \f[I]explain_pclose\fP(3),
and then the process terminates
by calling \f[CW]exit(EXIT_FAILURE)\fP.
.PP
This function is intended to be used in a fashion
similar to the following example:
.RS
.ft CW
.nf
int status = explain_pclose_or_die(fp);
.fi
.ft R
.RE
.TP 8n
\f[I]fp\fP
The fp, exactly as to be passed to the \f[I]pclose\fP(3) system call.
.TP 8n
Returns:
This function only returns on success, see \f[I]pclose\fP(3) for more
information. On failure, prints an explanation and exits.
.\" ------------------------------------------------------------------------
.SS explain_pclose_success_or_die
void explain_pclose_success_or_die(FILE *);
.PP
The \f[B]explain_pclose_success_or_die\fP function is used to call
the \f[I]pclose\fP(3) system call. On failure, including any exit
status other than EXIT_SUCCESS, an explanation will be printed to
\f[I]stderr\fP, obtained from \f[I]explain_pclose\fP(3), and then the
process terminates by calling \f[CW]exit(EXIT_FAILURE)\fP.
.PP
This function is intended to be used in a fashion
similar to the following example:
.RS
.ft CW
.nf
explain_pclose_success_or_die(fp);
.fi
.ft R
.RE
.TP 8n
\f[I]fp\fP
The fp, exactly as to be passed to the \f[I]pclose\fP(3) system call.
.TP 8n
Returns:
This function only returns on success.
On failure, prints an explanation and exits.
.\" ------------------------------------------------------------------------
.SS explain_pclose_success
int explain_pclose_success(FILE *fp);
.PP
The \f[B]explain_pclose_success\fP function is used to call
the \f[I]pclose\fP(3) system call. On failure, including any exit
status other than EXIT_SUCCESS, an explanation will be printed to
\f[I]stderr\fP, obtained from \f[I]explain_pclose\fP(3).
However, the priniting of an error message does \f[B]not\fP
also cause \f[I]exit\fP(2) to be called.
.PP
This function is intended to be used in a fashion
similar to the following example:
.RS
.ft CW
.nf
int status = explain_pclose_success(command);
.fi
.ft R
.RE
.TP 8n
\f[I]fp\fP
The fp, exactly as to be passed to the \f[I]pclose\fP(3) system call.
.TP 8n
Returns:
the value returned by the \f[I]pclose\fP(3) system call.
In all cases other than EXIT_SUCCESS, an error message will also have
been printed to stderr.
.\" ----------------------------------------------------
.SH SEE ALSO
.TP 8n
\f[I]pclose\fP(3)
process I/O
.TP 8n
\f[I]explain_pclose\fP(3)
explain \f[I]pclose\fP(3) errors
.TP 8n
\f[I]exit\fP(2)
terminate the calling process
.\" ----------------------------------------------------
.SH COPYRIGHT
.so etc/version.so
.if n .ds C) (C)
.if t .ds C) \(co
libexplain version \*(v)
.br
Copyright \*(C) 2009 Peter Miller
.\" vim:ts=8:sw=4:et
|
