1explain_tcgetattr(3) Library Functions Manual explain_tcgetattr(3)
2
6 explain_tcgetattr - explain tcgetattr(3) errors
7
9 #include <libexplain/tcgetattr.h>
10 const char *explain_tcgetattr(int fildes, struct termios *data);
11 const char *explain_errno_tcgetattr(int errnum, int fildes, struct
12 termios *data);
13 void explain_message_tcgetattr(char *message, int message_size, int
14 fildes, struct termios *data);
15 void explain_message_errno_tcgetattr(char *message, int message_size,
16 int errnum, int fildes, struct termios *data);
17
19 These functions may be used to obtain explanations for errors returned
20 by the tcgetattr(3) system call.
21 explain_tcgetattr
23 const char *explain_tcgetattr(int fildes, struct termios *data);
24 The explain_tcgetattr function is used to obtain an explanation of an
26 error returned by the tcgetattr(3) system call. The least the message
27 will contain is the value of strerror(errno), but usually it will do
28 much better, and indicate the underlying cause in more detail.
29 The errno global variable will be used to obtain the error value to be
31 decoded.
32 fildes The original fildes, exactly as passed to the tcgetattr(3) sys‐
34 tem call.
35 data The original data, exactly as passed to the tcgetattr(3) system
37 call.
38 Returns:
40 The message explaining the error. This message buffer is shared
41 by all libexplain functions which do not supply a buffer in
42 their argument list. This will be overwritten by the next call
43 to any libexplain function which shares this buffer, including
44 other threads.
45 Note: This function is not thread safe, because it shares a return buf‐
47 fer across all threads, and many other functions in this library.
48 Example: This function is intended to be used in a fashion similar to
50 the following example:
51 if (tcgetattr(fildes, data) < 0)
52 {
53 fprintf(stderr, "%s\n", explain_tcgetattr(fildes, data));
54 exit(EXIT_FAILURE);
55 }
56 The above code example is available pre‐packaged as the explain_tcge‐
58 tattr_or_die(3) function.
59 explain_errno_tcgetattr
61 const char *explain_errno_tcgetattr(int errnum, int fildes, struct
62 termios *data);
63 The explain_errno_tcgetattr function is used to obtain an explanation
65 of an error returned by the tcgetattr(3) system call. The least the
66 message will contain is the value of strerror(errno), but usually it
67 will do much better, and indicate the underlying cause in more detail.
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 tcgetattr(3) sys‐
76 tem call.
77 data The original data, exactly as passed to the tcgetattr(3) system
79 call.
80 Returns:
82 The message explaining the error. This message buffer is shared
83 by all libexplain functions which do not supply a buffer in
84 their argument list. This will be overwritten by the next call
85 to any libexplain function which shares this buffer, including
86 other threads.
87 Note: This function is not thread safe, because it shares a return buf‐
89 fer across all threads, and many other functions in this library.
90 Example: This function is intended to be used in a fashion similar to
92 the following example:
93 if (tcgetattr(fildes, data) < 0)
94 {
95 int err = errno;
96 fprintf(stderr, "%s\n", explain_errno_tcgetattr(err, fildes,
97 data));
98 exit(EXIT_FAILURE);
99 }
100 The above code example is available pre‐packaged as the explain_tcge‐
102 tattr_or_die(3) function.
103 explain_message_tcgetattr
105 void explain_message_tcgetattr(char *message, int message_size, int
106 fildes, struct termios *data);
107 The explain_message_tcgetattr function is used to obtain an explanation
109 of an error returned by the tcgetattr(3) system call. The least the
110 message will contain is the value of strerror(errno), but usually it
111 will do much better, and indicate the underlying cause in more detail.
112 The errno global variable will be used to obtain the error value to be
114 decoded.
115 message The location in which to store the returned message. If a suit‐
117 able message return buffer is supplied, this function is thread
118 safe.
119 message_size
121 The size in bytes of the location in which to store the
122 returned message.
123 fildes The original fildes, exactly as passed to the tcgetattr(3) sys‐
125 tem call.
126 data The original data, exactly as passed to the tcgetattr(3) system
128 call.
129 Example: This function is intended to be used in a fashion similar to
131 the following example:
132 if (tcgetattr(fildes, data) < 0)
133 {
134 char message[3000];
135 explain_message_tcgetattr(message, sizeof(message), fildes,
136 data);
137 fprintf(stderr, "%s\n", message);
138 exit(EXIT_FAILURE);
139 }
140 The above code example is available pre‐packaged as the explain_tcge‐
142 tattr_or_die(3) function.
143 explain_message_errno_tcgetattr
145 void explain_message_errno_tcgetattr(char *message, int message_size,
146 int errnum, int fildes, struct termios *data);
147 The explain_message_errno_tcgetattr function is used to obtain an
149 explanation of an error returned by the tcgetattr(3) system call. The
150 least the message will contain is the value of strerror(errno), but
151 usually it will do much better, and indicate the underlying cause in
152 more detail.
153 message The location in which to store the returned message. If a suit‐
155 able message return buffer is supplied, this function is thread
156 safe.
157 message_size
159 The size in bytes of the location in which to store the
160 returned message.
161 errnum The error value to be decoded, usually obtained from the errno
163 global variable just before this function is called. This is
164 necessary if you need to call any code between the system call
165 to be explained and this function, because many libc functions
166 will alter the value of errno.
167 fildes The original fildes, exactly as passed to the tcgetattr(3) sys‐
169 tem call.
170 data The original data, exactly as passed to the tcgetattr(3) system
172 call.
173 Example: This function is intended to be used in a fashion similar to
175 the following example:
176 if (tcgetattr(fildes, data) < 0)
177 {
178 int err = errno;
179 char message[3000];
180 explain_message_errno_tcgetattr(message, sizeof(message),
181 err, fildes, data);
182 fprintf(stderr, "%s\n", message);
183 exit(EXIT_FAILURE);
184 }
185 The above code example is available pre‐packaged as the explain_tcge‐
187 tattr_or_die(3) function.
188
190 tcgetattr(3)
191 get terminal parameters
192 explain_tcgetattr_or_die(3)
194 get terminal parameters and report errors
195
197 libexplain version 1.4
198 Copyright (C) 2009 Peter Miller
199 explain_tcgetattr(3)