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

NAME

6       explain_close - explain close(2) errors
7

SYNOPSIS

9       #include <libexplain/close.h>
10       const char *explain_close(int fildes);
11       const char *explain_errno_close(int errnum, int fildes);
12       void   explain_message_close(char   *message,   int  message_size,  int
13       fildes);
14       void explain_message_errno_close(char *message, int  message_size,  int
15       errnum, int fildes);
16

DESCRIPTION

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

SEE ALSO

160       close   close a file descriptor
161
162       explain_close_or_die
163               close a file descriptor and report errors
164
166       libexplain version 1.4
167       Copyright (C) 2008 Peter Miller
168
169
170
171                                                              explain_close(3)
Impressum