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

NAME

6       explain_dup - explain dup(2) errors
7

SYNOPSIS

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

DESCRIPTION

17       These functions may be used to obtain explanations for errors  returned
18       by the dup(2) system call.
19
20   explain_dup
21       const char *explain_dup(int fildes);
22
23       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
28       The errno global variable will be used to obtain the error value to  be
29       decoded.
30
31       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
39       fildes  The original fildes, exactly as passed  to  the  dup(2)  system
40               call.
41
42       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
49       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
52   explain_errno_dup
53       const char *explain_errno_dup(int errnum, int fildes);
54
55       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
60       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
69       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
75       fildes  The original fildes, exactly as passed  to  the  dup(2)  system
76               call.
77
78       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
85       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
88   explain_message_dup
89       void explain_message_dup(char *message, int message_size, int fildes);
90
91       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
96       The  errno global variable will be used to obtain the error value to be
97       decoded.
98
99       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
109       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
113       message_size
114               The  size  in  bytes  of  the  location  in  which to store the
115               returned message.
116
117       fildes  The original fildes, exactly as passed  to  the  dup(2)  system
118               call.
119
120   explain_message_errno_dup
121       void  explain_message_errno_dup(char  *message,  int  message_size, int
122       errnum, int fildes);
123
124       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
129       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
140       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
144       message_size
145               The size in bytes  of  the  location  in  which  to  store  the
146               returned message.
147
148       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
154       fildes  The  original  fildes,  exactly  as passed to the dup(2) system
155               call.
156

SEE ALSO

158       dup(2)  duplicate a file descriptor
159
160       explain_dup_or_die(3)
161               duplicate a file descriptor and report errors
162
164       libexplain version 1.4
165       Copyright (C) 2008 Peter Miller
166
167
168
169                                                                explain_dup(3)
Impressum