1explain_dup(3) Library Functions Manual explain_dup(3)
2
6 explain_dup - explain dup(2) errors
7
9 #include <libexplain/dup.h>
10 const char *explain_dup(int fildes);
11 const char *explain_errno_dup(int errnum, int fildes);
12 void explain_message_dup(char *message, int message_size, int fildes);
13 void explain_message_errno_dup(char *message, int message_size, int
14 errnum, int fildes);
15
17 These functions may be used to obtain explanations for errors returned
18 by the dup(2) system call.
19 explain_dup
21 const char *explain_dup(int fildes);
22 The explain_dup function is used to obtain an explanation of an error
24 returned by the dup(2) system call. The least the message will contain
25 is the value of strerror(errno), but usually it will do much better,
26 and indicate the underlying cause in more detail.
27 The errno global variable will be used to obtain the error value to be
29 decoded.
30 This function is intended to be used in a fashion similar to the fol‐
32 lowing example:
33 if (dup(fildes) < 0)
34 {
35 fprintf(stderr, "%s\n", explain_dup(fildes));
36 exit(EXIT_FAILURE);
37 }
38 fildes The original fildes, exactly as passed to the dup(2) system
40 call.
41 Returns:
43 The message explaining the error. This message buffer is
44 shared by all libexplain functions which do not supply a buffer
45 in their argument list. This will be overwritten by the next
46 call to any libexplain function which shares this buffer,
47 including other threads.
48 Note: This function is not thread safe, because it shares a return buf‐
50 fer across all threads, and many other functions in this library.
51 explain_errno_dup
53 const char *explain_errno_dup(int errnum, int fildes);
54 The explain_errno_dup function is used to obtain an explanation of an
56 error returned by the dup(2) system call. The least the message will
57 contain is the value of strerror(errnum), but usually it will do much
58 better, and indicate the underlying cause in more detail.
59 This function is intended to be used in a fashion similar to the fol‐
61 lowing example:
62 if (dup(fildes) < 0)
63 {
64 int err = errno;
65 fprintf(stderr, "%s\n", explain_errno_dup(err, fildes));
66 exit(EXIT_FAILURE);
67 }
68 errnum The error value to be decoded, usually obtained from the errno
70 global variable just before this function is called. This is
71 necessary if you need to call any code between the system call
72 to be explained and this function, because many libc functions
73 will alter the value of errno.
74 fildes The original fildes, exactly as passed to the dup(2) system
76 call.
77 Returns:
79 The message explaining the error. This message buffer is
80 shared by all libexplain functions which do not supply a buffer
81 in their argument list. This will be overwritten by the next
82 call to any libexplain function which shares this buffer,
83 including other threads.
84 Note: This function is not thread safe, because it shares a return buf‐
86 fer across all threads, and many other functions in this library.
87 explain_message_dup
89 void explain_message_dup(char *message, int message_size, int fildes);
90 The explain_message_dup function may be used to obtain an explanation
92 of an error returned by the dup(2) system call. The least the message
93 will contain is the value of strerror(errno), but usually it will do
94 much better, and indicate the underlying cause in more detail.
95 The errno global variable will be used to obtain the error value to be
97 decoded.
98 This function is intended to be used in a fashion similar to the fol‐
100 lowing example:
101 if (dup(fildes) < 0)
102 {
103 char message[3000];
104 explain_message_dup(message, sizeof(message), fildes);
105 fprintf(stderr, "%s\n", message);
106 exit(EXIT_FAILURE);
107 }
108 message The location in which to store the returned message. If a
110 suitable message return buffer is supplied, this function is
111 thread safe.
112 message_size
114 The size in bytes of the location in which to store the
115 returned message.
116 fildes The original fildes, exactly as passed to the dup(2) system
118 call.
119 explain_message_errno_dup
121 void explain_message_errno_dup(char *message, int message_size, int
122 errnum, int fildes);
123 The explain_message_errno_dup function may be used to obtain an expla‐
125 nation of an error returned by the dup(2) system call. The least the
126 message will contain is the value of strerror(errnum), but usually it
127 will do much better, and indicate the underlying cause in more detail.
128 This function is intended to be used in a fashion similar to the fol‐
130 lowing example:
131 if (dup(fildes) < 0)
132 {
133 int err = errno;
134 char message[3000];
135 explain_message_errno_dup(message, sizeof(message), err, fildes);
136 fprintf(stderr, "%s\n", message);
137 exit(EXIT_FAILURE);
138 }
139 message The location in which to store the returned message. If a
141 suitable message return buffer is supplied, this function is
142 thread safe.
143 message_size
145 The size in bytes of the location in which to store the
146 returned message.
147 errnum The error value to be decoded, usually obtained from the errno
149 global variable just before this function is called. This is
150 necessary if you need to call any code between the system call
151 to be explained and this function, because many libc functions
152 will alter the value of errno.
153 fildes The original fildes, exactly as passed to the dup(2) system
155 call.
156
158 dup(2) duplicate a file descriptor
159 explain_dup_or_die(3)
161 duplicate a file descriptor and report errors
162
164 libexplain version 0.40
165 Copyright (C) 2008 Peter Miller
166 explain_dup(3)