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

NAME

6       explain_dup2 - explain dup2(2) errors
7

SYNOPSIS

9       #include <libexplain/dup2.h>
10       const char *explain_dup2(int oldfd, int newfd);
11       const char *explain_errno_dup2(int errnum, int oldfd, int newfd);
12       void  explain_message_dup2(char  *message, int message_size, int oldfd,
13       int newfd);
14       void explain_message_errno_dup2(char *message,  int  message_size,  int
15       errnum, int oldfd, int newfd);
16

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the dup2(2) system call.
20
21   explain_dup2
22       const char *explain_dup2(int oldfd, int newfd);
23
24       The explain_dup2 function is used to obtain an explanation of an  error
25       returned  by  the dup2(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 (dup2(oldfd, newfd) < 0)
35              {
36                  fprintf(stderr, "%s\n", explain_dup2(oldfd, newfd));
37                  exit(EXIT_FAILURE);
38              }
39
40       oldfd   The  original  oldfd,  exactly  as passed to the dup2(2) system
41               call.
42
43       newfd   The original newfd, exactly as passed  to  the  dup2(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_dup2
57       const char *explain_errno_dup2(int errnum, int oldfd, int newfd);
58
59       The explain_errno_dup2 function is used to obtain an explanation of  an
60       error  returned by the dup2(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 (dup2(oldfd, newfd) < 0)
67              {
68                  int err = errno;
69                  fprintf(stderr, "%s\n", explain_errno_dup2(err, oldfd, newfd));
70                  exit(EXIT_FAILURE);
71              }
72
73       errnum  The error value to be decoded, usually obtained from the  errno
74               global  variable  just before this function is called.  This is
75               necessary if you need to call any code between the system  call
76               to  be explained and this function, because many libc functions
77               will alter the value of errno.
78
79       oldfd   The original oldfd, exactly as passed  to  the  dup2(2)  system
80               call.
81
82       newfd   The  original  newfd,  exactly  as passed to the dup2(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_dup2
96       void  explain_message_dup2(char  *message, int message_size, int oldfd,
97       int newfd);
98
99       The explain_message_dup2 function may be used to  obtain an explanation
100       of an error returned by the dup2(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 (dup2(oldfd, newfd) < 0)
110              {
111                  char message[3000];
112                  explain_message_dup2(message, sizeof(message), oldfd, newfd);
113                  fprintf(stderr, "%s\n", message);
114                  exit(EXIT_FAILURE);
115              }
116
117       message The  location  in  which  to  store the returned message.  If a
118               suitable message return buffer is supplied,  this  function  is
119               thread safe.
120
121       message_size
122               The  size  in  bytes  of  the  location  in  which to store the
123               returned message.
124
125       oldfd   The original oldfd, exactly as passed  to  the  dup2(2)  system
126               call.
127
128       newfd   The  original  newfd,  exactly  as passed to the dup2(2) system
129               call.
130
131   explain_message_errno_dup2
132       void explain_message_errno_dup2(char *message,  int  message_size,  int
133       errnum, int oldfd, int newfd);
134
135       The explain_message_errno_dup2 function may be used to obtain an expla‐
136       nation of an error returned by the dup2(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 (dup2(oldfd, newfd) < 0)
143              {
144                  int err = errno;
145                  char message[3000];
146                  explain_message_errno_dup2(message, sizeof(message), err, oldfd, newfd);
147                  fprintf(stderr, "%s\n", message);
148                  exit(EXIT_FAILURE);
149              }
150
151       message The  location  in  which  to  store the returned message.  If a
152               suitable message return buffer is supplied,  this  function  is
153               thread safe.
154
155       message_size
156               The  size  in  bytes  of  the  location  in  which to store the
157               returned message.
158
159       errnum  The error value to be decoded, usually obtained from the  errno
160               global  variable  just before this function is called.  This is
161               necessary if you need to call any code between the system  call
162               to  be explained and this function, because many libc functions
163               will alter the value of errno.
164
165       oldfd   The original oldfd, exactly as passed  to  the  dup2(2)  system
166               call.
167
168       newfd   The  original  newfd,  exactly  as passed to the dup2(2) system
169               call.
170

SEE ALSO

172       dup2(2) duplicate a file descriptor
173
174       explain_dup2_or_die(3)
175               duplicate a file descriptor and report errors
176
178       libexplain version 0.40
179       Copyright (C) 2008 Peter Miller
180
181
182
183                                                               explain_dup2(3)
Impressum