1explain_pipe(3)            Library Functions Manual            explain_pipe(3)
2
3
4

NAME

6       explain_pipe - explain pipe(2) errors
7

SYNOPSIS

9       #include <libexplain/pipe.h>
10       const char *explain_pipe(int *pipefd);
11       const char *explain_errno_pipe(int errnum, int *pipefd);
12       void   explain_message_pipe(char   *message,   int   message_size,  int
13       *pipefd);
14       void explain_message_errno_pipe(char *message,  int  message_size,  int
15       errnum, int *pipefd);
16

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the pipe(2) system call.
20
21   explain_pipe
22       const char *explain_pipe(int *pipefd);
23
24       The explain_pipe function is used to obtain an explanation of an  error
25       returned  by  the pipe(2) system call.  The least the message will con‐
26       tain is the value of strerror(errno), but usually it will do much  bet‐
27       ter, and indicate the underlying cause in more detail.
28
29       The  errno global variable will be used to obtain the error value to be
30       decoded.
31
32       This function is intended to be used in a fashion similar to  the  fol‐
33       lowing example:
34              if (pipe(pipefd) < 0)
35              {
36                  fprintf(stderr, "%s\n", explain_pipe(pipefd));
37                  exit(EXIT_FAILURE);
38              }
39
40       The   above   code   example   is   available   pre‐packaged   as   the
41       explain_pipe_or_die(3) function.
42
43       pipefd  The original pipefd, exactly as passed to  the  pipe(2)  system
44               call.
45
46       Returns:
47               The  message  explaining  the  error.   This  message buffer is
48               shared by all libexplain functions which do not supply a buffer
49               in  their  argument list.  This will be overwritten by the next
50               call to any  libexplain  function  which  shares  this  buffer,
51               including other threads.
52
53       Note: This function is not thread safe, because it shares a return buf‐
54       fer across all threads, and many other functions in this library.
55
56   explain_errno_pipe
57       const char *explain_errno_pipe(int errnum, int *pipefd);
58
59       The explain_errno_pipe function is used to obtain an explanation of  an
60       error  returned by the pipe(2) system call.  The least the message will
61       contain is the value of strerror(errnum), but usually it will  do  much
62       better, and indicate the underlying cause in more detail.
63
64       This  function  is intended to be used in a fashion similar to the fol‐
65       lowing example:
66              if (pipe(pipefd) < 0)
67              {
68                  int err = errno;
69                  fprintf(stderr, "%s\n", explain_errno_pipe(err, pipefd));
70                  exit(EXIT_FAILURE);
71              }
72
73       The   above   code   example   is   available   pre‐packaged   as   the
74       explain_pipe_or_die(3) function.
75
76       errnum  The  error value to be decoded, usually obtained from the errno
77               global variable just before this function is called.   This  is
78               necessary  if you need to call any code between the system call
79               to be explained and this function, because many libc  functions
80               will alter the value of errno.
81
82       pipefd  The  original  pipefd,  exactly as passed to the pipe(2) system
83               call.
84
85       Returns:
86               The message explaining  the  error.   This  message  buffer  is
87               shared by all libexplain functions which do not supply a buffer
88               in their argument list.  This will be overwritten by  the  next
89               call  to  any  libexplain  function  which  shares this buffer,
90               including other threads.
91
92       Note: This function is not thread safe, because it shares a return buf‐
93       fer across all threads, and many other functions in this library.
94
95   explain_message_pipe
96       void   explain_message_pipe(char   *message,   int   message_size,  int
97       *pipefd);
98
99       The explain_message_pipe function may be used to  obtain an explanation
100       of an error returned by the pipe(2) system call.  The least the message
101       will contain is the value of strerror(errno), but usually  it  will  do
102       much better, and indicate the underlying cause in more detail.
103
104       The  errno global variable will be used to obtain the error value to be
105       decoded.
106
107       This function is intended to be used in a fashion similar to  the  fol‐
108       lowing example:
109              if (pipe(pipefd) < 0)
110              {
111                  char message[3000];
112                  explain_message_pipe(message, sizeof(message), pipefd);
113                  fprintf(stderr, "%s\n", message);
114                  exit(EXIT_FAILURE);
115              }
116
117       The   above   code   example   is   available   pre‐packaged   as   the
118       explain_pipe_or_die(3) function.
119
120       message The location in which to store  the  returned  message.   If  a
121               suitable  message  return  buffer is supplied, this function is
122               thread safe.
123
124       message_size
125               The size in bytes  of  the  location  in  which  to  store  the
126               returned message.
127
128       pipefd  The  original  pipefd,  exactly as passed to the pipe(2) system
129               call.
130
131   explain_message_errno_pipe
132       void explain_message_errno_pipe(char *message,  int  message_size,  int
133       errnum, int *pipefd);
134
135       The explain_message_errno_pipe function may be used to obtain an expla‐
136       nation of an error returned by the pipe(2) system call.  The least  the
137       message  will  contain is the value of strerror(errnum), but usually it
138       will do much better, and indicate the underlying cause in more detail.
139
140       This function is intended to be used in a fashion similar to  the  fol‐
141       lowing example:
142              if (pipe(pipefd) < 0)
143              {
144                  int err = errno;
145                  char message[3000];
146                  explain_message_errno_pipe(message, sizeof(message), err, pipefd);
147                  fprintf(stderr, "%s\n", message);
148                  exit(EXIT_FAILURE);
149              }
150
151       The   above   code   example   is   available   pre‐packaged   as   the
152       explain_pipe_or_die(3) function.
153
154       message The location in which to store  the  returned  message.   If  a
155               suitable  message  return  buffer is supplied, this function is
156               thread safe.
157
158       message_size
159               The size in bytes  of  the  location  in  which  to  store  the
160               returned message.
161
162       errnum  The  error value to be decoded, usually obtained from the errno
163               global variable just before this function is called.   This  is
164               necessary  if you need to call any code between the system call
165               to be explained and this function, because many libc  functions
166               will alter the value of errno.
167
168       pipefd  The  original  pipefd,  exactly as passed to the pipe(2) system
169               call.
170

SEE ALSO

172       pipe(2) create pipe
173
174       explain_pipe_or_die(3)
175               create pipe and report errors
176
178       libexplain version 0.40
179       Copyright (C) 2009 Peter Miller
180
181
182
183                                                               explain_pipe(3)
Impressum