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

NAME

6       explain_tcflow - explain tcflow(3) errors
7

SYNOPSIS

9       #include <libexplain/tcflow.h>
10       const char *explain_tcflow(int fildes, int action);
11       const char *explain_errno_tcflow(int errnum, int fildes, int action);
12       void explain_message_tcflow(char *message, int message_size, int
13       fildes, int action);
14       void explain_message_errno_tcflow(char *message, int message_size, int
15       errnum, int fildes, int action);
16

DESCRIPTION

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

SEE ALSO

187       tcflow(3)
188               terminal flow control
189
190       explain_tcflow_or_die(3)
191               terminal flow control and report errors
192
194       libexplain version 1.4
195       Copyright (C) 2009 Peter Miller
196
197
198
199                                                             explain_tcflow(3)
Impressum