1explain_tcsetattr(3) Library Functions Manual explain_tcsetattr(3)
2
6 explain_tcsetattr - explain tcsetattr(3) errors
7
9 #include <libexplain/tcsetattr.h>
10 const char *explain_tcsetattr(int fildes, int options, const struct
11 termios *data);
12 const char *explain_errno_tcsetattr(int errnum, int fildes, int
13 options, const struct termios *data);
14 void explain_message_tcsetattr(char *message, int message_size, int
15 fildes, int options, const struct termios *data);
16 void explain_message_errno_tcsetattr(char *message, int message_size,
17 int errnum, int fildes, int options, const struct termios *data);
18
20 These functions may be used to obtain explanations for errors returned
21 by the tcsetattr(3) system call.
22 explain_tcsetattr
24 const char *explain_tcsetattr(int fildes, int options, const struct
25 termios *data);
26 The explain_tcsetattr function is used to obtain an explanation of an
28 error returned by the tcsetattr(3) system call. The least the message
29 will contain is the value of strerror(errno), but usually it will do
30 much better, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 fildes The original fildes, exactly as passed to the tcsetattr(3) sys‐
36 tem call.
37 options The original options, exactly as passed to the tcsetattr(3)
39 system call.
40 data The original data, exactly as passed to the tcsetattr(3) system
42 call.
43 Returns:
45 The message explaining the error. This message buffer is shared
46 by all libexplain functions which do not supply a buffer in
47 their argument list. This will be overwritten by the next call
48 to any libexplain function which shares this buffer, including
49 other threads.
50 Note: This function is not thread safe, because it shares a return buf‐
52 fer across all threads, and many other functions in this library.
53 Example: This function is intended to be used in a fashion similar to
55 the following example:
56 if (tcsetattr(fildes, options, data) < 0)
57 {
58 fprintf(stderr, "%s\n", explain_tcsetattr(fildes, options,
59 data));
60 exit(EXIT_FAILURE);
61 }
62 The above code example is available pre‐packaged as the explain_tcse‐
64 tattr_or_die(3) function.
65 explain_errno_tcsetattr
67 const char *explain_errno_tcsetattr(int errnum, int fildes, int
68 options, const struct termios *data);
69 The explain_errno_tcsetattr function is used to obtain an explanation
71 of an error returned by the tcsetattr(3) system call. The least the
72 message will contain is the value of strerror(errno), but usually it
73 will do much better, and indicate the underlying cause in more detail.
74 errnum The error value to be decoded, usually obtained from the errno
76 global variable just before this function is called. This is
77 necessary if you need to call any code between the system call
78 to be explained and this function, because many libc functions
79 will alter the value of errno.
80 fildes The original fildes, exactly as passed to the tcsetattr(3) sys‐
82 tem call.
83 options The original options, exactly as passed to the tcsetattr(3)
85 system call.
86 data The original data, exactly as passed to the tcsetattr(3) system
88 call.
89 Returns:
91 The message explaining the error. This message buffer is shared
92 by all libexplain functions which do not supply a buffer in
93 their argument list. This will be overwritten by the next call
94 to any libexplain function which shares this buffer, including
95 other threads.
96 Note: This function is not thread safe, because it shares a return buf‐
98 fer across all threads, and many other functions in this library.
99 Example: This function is intended to be used in a fashion similar to
101 the following example:
102 if (tcsetattr(fildes, options, data) < 0)
103 {
104 int err = errno;
105 fprintf(stderr, "%s\n", explain_errno_tcsetattr(err, fildes,
106 options, data));
107 exit(EXIT_FAILURE);
108 }
109 The above code example is available pre‐packaged as the explain_tcse‐
111 tattr_or_die(3) function.
112 explain_message_tcsetattr
114 void explain_message_tcsetattr(char *message, int message_size, int
115 fildes, int options, const struct termios *data);
116 The explain_message_tcsetattr function is used to obtain an explanation
118 of an error returned by the tcsetattr(3) system call. The least the
119 message will contain is the value of strerror(errno), but usually it
120 will do much better, and indicate the underlying cause in more detail.
121 The errno global variable will be used to obtain the error value to be
123 decoded.
124 message The location in which to store the returned message. If a suit‐
126 able message return buffer is supplied, this function is thread
127 safe.
128 message_size
130 The size in bytes of the location in which to store the
131 returned message.
132 fildes The original fildes, exactly as passed to the tcsetattr(3) sys‐
134 tem call.
135 options The original options, exactly as passed to the tcsetattr(3)
137 system call.
138 data The original data, exactly as passed to the tcsetattr(3) system
140 call.
141 Example: This function is intended to be used in a fashion similar to
143 the following example:
144 if (tcsetattr(fildes, options, data) < 0)
145 {
146 char message[3000];
147 explain_message_tcsetattr(message, sizeof(message), fildes,
148 options, data);
149 fprintf(stderr, "%s\n", message);
150 exit(EXIT_FAILURE);
151 }
152 The above code example is available pre‐packaged as the explain_tcse‐
154 tattr_or_die(3) function.
155 explain_message_errno_tcsetattr
157 void explain_message_errno_tcsetattr(char *message, int message_size,
158 int errnum, int fildes, int options, const struct termios *data);
159 The explain_message_errno_tcsetattr function is used to obtain an
161 explanation of an error returned by the tcsetattr(3) system call. The
162 least the message will contain is the value of strerror(errno), but
163 usually it will do much better, and indicate the underlying cause in
164 more detail.
165 message The location in which to store the returned message. If a suit‐
167 able message return buffer is supplied, this function is thread
168 safe.
169 message_size
171 The size in bytes of the location in which to store the
172 returned message.
173 errnum The error value to be decoded, usually obtained from the errno
175 global variable just before this function is called. This is
176 necessary if you need to call any code between the system call
177 to be explained and this function, because many libc functions
178 will alter the value of errno.
179 fildes The original fildes, exactly as passed to the tcsetattr(3) sys‐
181 tem call.
182 options The original options, exactly as passed to the tcsetattr(3)
184 system call.
185 data The original data, exactly as passed to the tcsetattr(3) system
187 call.
188 Example: This function is intended to be used in a fashion similar to
190 the following example:
191 if (tcsetattr(fildes, options, data) < 0)
192 {
193 int err = errno;
194 char message[3000];
195 explain_message_errno_tcsetattr(message, sizeof(message),
196 err, fildes, options, data);
197 fprintf(stderr, "%s\n", message);
198 exit(EXIT_FAILURE);
199 }
200 The above code example is available pre‐packaged as the explain_tcse‐
202 tattr_or_die(3) function.
203
205 tcsetattr(3)
206 set terminal attributes
207 explain_tcsetattr_or_die(3)
209 set terminal attributes and report errors
210
212 libexplain version 0.40
213 Copyright (C) 2009 Peter Miller
214 explain_tcsetattr(3)