1gensio_control(3) Library Functions Manual gensio_control(3)
2
6 gensio_control - Perform gensio-specific actions
7
9 #include <gensio/gensio.h>
10 int gensio_control(struct gensio *io, int depth, bool get,
12 unsigned int option,
13 char *data, gensiods *datalen);
14 typedef void (*gensio_control_done)(struct gensio *io, int err,
16 const char *buf, gensiods len,
17 void *cb_data);
18 int gensio_acontrol(struct gensio *io, int depth, bool get,
20 unsigned int option,
21 char *data, gensiods datalen,
22 gensio_control_done done, void *cb_data,
23 gensio_time *timeout);
24 int gensio_acontrol_s(struct gensio *io, int depth, bool get,
26 unsigned int option,
27 char *data, gensiods *datalen,
28 gensio_time *timeout);
29 int gensio_acontrol_s_intr(struct gensio *io, int depth, bool get,
31 unsigned int option,
32 char *data, gensiods *datalen,
33 gensio_time *timeout);
34 const char *gensio_parity_to_str(unsigned int ival);
36 int gensio_str_to_parity(char *sval);
38 const char *gensio_flowcontrol_to_str(unsigned int ival);
40 int gensio_str_to_flowcontrol(char *sval);
42 const char *gensio_onoff_to_str(unsigned int ival);
44 int gensio_str_to_onoff(char *sval);
46
48 gensio_control performs a gensio-specific operation on the gensio (if
49 depth is 0) or one of its children ( depth > 0). If depth is GEN‐
50 SIO_CONTROL_DEPTH_ALL, then call all the children with the data.
51 GE_NOTSUP error returns from individual gensios are ignored in that
52 case, but it will stop at the first error besides that. If depth is
53 GENSIO_CONTROL_DEPTH_FIRST, it will return on the first gensio that
54 doesn't return GE_NOTSUP. It returns GE_NOTFOUND if nothing handled
55 it.
56 If you specify a depth >= 0, and depth is greater than the number of
58 gensios in the stack, this will return GE_NOTFOUND. This way you can
59 know if you reached the bottom of the stack.
60 Most controls use normal strings for configuration, a control will be
62 this way unless othersise specified. Some controls allow binary infor‐
63 mation to be passed.
64 If get is GENSIO_CONTROL_GET (true), attempt to fetch the option. You
66 cannot use GENSIO_CONTROL_DEPTH_ALL with a fetch. To fetch an option,
67 you must pass in data long enough to hold the output and set datalen to
68 the number of bytes available in data for the output. It will return
69 the length of the string (like strlen, not including the terminating
70 nil) or binary data in datalen.
71 An operation with get set to GENSIO_CONTROL_SET (false) is a set opera‐
73 tion, it will set values or controls in the gensio. For string values,
74 datalen is not used in a put operation or for determining the length of
75 the input string in data, it must be a nil terminated string. For bi‐
76 nary values, datalen must be provided.
77 All normal controls fetch data immediately and do not block.
79 gensio_acontrol does a control that is asynchronous, meaning that it is
81 not finished when the function returns. If it returns zero, the done
82 callback will be called with the result when the operation completes.
83 All asynchronous control options start with GENSIO_ACONTROL_xxx. Asyn‐
84 chronous controls do not allow GENSIO_CONTROL_DEPTH_ALL, they can only
85 be called on a single gensio in the stack.
86 gensio_acontrol_s does an asynchronous control, but waits until the op‐
88 eration completes using an os function waiter.
89 The timeout values on the acontrol functions is a hint to the code, it
91 may or may not have any effect. It is not necessarily updated to the
92 remaining time, either. For telnet, this updates the default time to
93 wait for a result. For serialdev it has no effect, as those operations
94 are immediate. It is ignored for ipmisol.
95 A get operation is alway indepotent (it won't change anything, so mul‐
97 tiple calls will not have any effect on the state of the system). A
98 get operation may or may not use information passed in data, and re‐
99 turns information in the data field.
100 If the output does not fit in a get operation, datalen is updated to
102 where it would have been if it had enough bytes (one less than the to‐
103 tal number of bytes required for string controls), but the output in
104 data is truncated (and nil terminated if possible for string controls).
105 This can be used to probe to see how long a buffer is required by pass‐
106 ing in a zero *datalen, and then allocating *datalen (+ 1 for string
107 gensios) and calling the function again with that data.
108 gensio control operations in option depend on the particular gensio.
110 Below some are documented, but there may be other controls available.
111 See the gensio documentation in gensio(5) for details.
112 GENSIO_CONTROL_NODELAY
114 Set the enable/disable for any NAGLE type algorithms. For put the data
115 should be a string "1" to disable delay, or "0" to enable delay. Re‐
116 turn value from a get is a string "1" or "0".
117 GENSIO_CONTROL_STREAMS
119 Return information about incoming and outgoing streams for the gensio.
120 This is read(get)-only and returns the value in the data in the form
121 "instream=<n>,ostream=<n>". Used by SCTP.
122 GENSIO_CONTROL_SEND_BREAK
124 Request that a break be sent over the line (primarily for telnet).
125 GENSIO_CONTROL_GET_PEER_CERT_NAME
127 Return the object from the certificate from the remote end. This is
128 primarily for SSL and certauth so the application can validate the cer‐
129 tificate's common name, but it can fetch any object from the certifi‐
130 cate.
131 There are two ways to use this interface: fetch by index or fetch by
133 object type.
134 To fetch by index, just pass in a number in the data, like "0" and it
136 will fetch the value at that index.
137 To fetch by object type, pass in a number and the object type separated
139 by a comma. The object type to fetch is SN (short name) or LN (long
140 name) descriptor per /usr/include/openssl/object.h. Like "CN" or "com‐
141 monName". The index should be one less than the start search, you
142 should use -1, for instance to fetch the first index.
143 The data returned is in the form: "<index>,<sn>,<value>". Where sn is
145 the short name.
146 In fetch by object type mode, there may be more than one of an object
148 in a certificate, so this interface can handle that. just pass in the
149 index returned by the first into the second call and it will start af‐
150 ter that index. For instance, to fetch the first common name, do (with
151 error checking removed for clarity):
152 strcpy(data, "-1,CN");
154 gensio_control(io, 0, true, data, &len)
155 Say it returns "3,CN,MyName.org" You would use
157 strcpy(data, "3,CN");
159 gensio_control(io, 0, true, data, &len)
160 to get the next common name, which might be "4,CN,MyName2.org". You
162 get an GE_NOTFOUND at the end.
163 Returns GE_NOCERT if there is no remote certificate, GE_CERTINVAL if
165 the passed in object name is not valid, and GE_NOTFOUND if the object
166 was not available in the certificate.
167 GENSIO_CONTROL_CERT_AUTH
169 Set the certificate authority file to the string in data. If it ends
170 in '/', it is assumed to be a directory, otherwise it is assumed to be
171 a file. This generally must be done before authorization is done, gen‐
172 erally before open or in the GENSIO_EVENT_PRECERT_VERIFY event (see
173 gensio_event(3) for details).
174 GENSIO_CONTROL_USERNAME
176 Get/set the username for the gensio, generally the username sent from
177 the client end on a certauth gensio. This is always a string.
178 GENSIO_CONTROL_PASSWORD
180 Get/set the password for the gensio, generally the password sent from
181 the client end on a certauth gensio. This is always a string. On the
182 server side this will only be available in the GENSIO_EVENT_PASS‐
183 WORD_VERIFY event. and is cleared outside of that.
184 GENSIO_CONTROL_2FA
186 Get/set the 2-factor auth data for the gensio, generally the data sent
187 from the client end on a certauth gensio. This is non-nil terminated
188 binary data, generally. On the server side this will only be available
189 in the GENSIO_EVENT_PASSWORD_VERIFY event or the GENSIO_2FA_VERIFY
190 event and is cleared outside of that.
191 GENSIO_CONTROL_SERVICE
193 On a client, set the service data passed by the gensio to the server.
194 On a server, et the service sent from the gensio client, generally
195 available on a certauth server. Returns GE_DATAMISSING if a service
196 was not sent.
197 This is a binary control, so arbitrary data can be passed in the ser‐
199 vice.
200 GENSIO_CONTROL_CERT
202 Get the full certificate in text form sent from the other end.
203 GENSIO_CONTROL_CERT_FINGERPRINT
205 Get the fingerprint for the certificate from the other end.
206 GENSIO_CONTROL_ENVIRONMENT
208 Set the environment pointer for an exec. For pty and stdio connecter
209 gensios. The data is a pointer to an argv array (char * const envp[])
210 GENSIO_CONTROL_ARGS
212 Set the arguments for an exec. For pty and stdio connecter gensios.
213 The data is a pointer to an argv array (char * const argv[])
214 GENSIO_CONTROL_MAX_WRITE_PACKET
216 On a packet gensio, return the maximum packet size that can be sent.
217 Any write of this amount or less will be sent as a single message that
218 will be delivered as one read on the other end, or it will not be sent
219 at all (zero-byte send count).
220 GENSIO_CONTROL_EXIT_CODE
222 On a stdio connectors and pty gensios, the exit code of the process
223 that ran. This is only valid after close has completed. An integer
224 string is returned.
225 GENSIO_CONTROL_KILL_TASK
227 Attempt to terminate the task. The passed in string is converted (str‐
228 tol) to an integer, if if it non-zero, a forced kill (kill -9) is done,
229 otherwise a normal terminate is done.
230 GENSIO_CONTROL_WAIT_TASK
232 On a stdio connectors and pty gensios, do a waitpid on the process. If
233 it has closed, this will return success and the exit code in the
234 string. Otherwise it will return GE_NOTREADY.
235 GENSIO_CONTROL_ADD_MCAST
237 On UDP connections, add a multicast address that the socket will re‐
238 ceive packets on.
239 GENSIO_CONTROL_DEL_MCAST
241 On UDP connections, delete a multicast address that the socket will re‐
242 ceive packets on.
243 GENSIO_CONTROL_MCAST_LOOP
245 On UDP connections, sets whether multicast packets sent on the socket
246 will be received by the same machine. Takes/returns string boolean
247 "true" or "false". Defaults to false.
248 GENSIO_CONTROL_MCAST_TTL
250 Sets the multicast time-to-live. Takes/returns a string integer. The
251 default is 1, meaning multicast stays in the local network. Increasing
252 this value increases the number of hops over multicast routers a send
253 packet will traverse.
254 GENSIO_CONTROL_LADDR
256 Return the local address for the connection. Only for network connec‐
257 tions or sound devices.
258 For network devices, since a single gensio may have more than one local
260 address, this control provides a means to tell which one. The data
261 string passed in should be the string representation of a the number
262 (like created with snprintf()) for the particular index you want to
263 fetch. If you specify a number larger than the number of open listen
264 sockets, GE_NOTFOUND is returned. The return data is a string holding
265 the address.
266 Note that a single fetched string may contain more than one address.
268 These will be separated by semicolons. In some cases addresses may
269 change dynamically (like with SCTP), so you get a single set of ad‐
270 dresses.
271 For sound devices, pass in "in" or "out" in the string to get the full
273 card number or name that uniquely identifies the sound card.
274 GENSIO_CONTROL_RADDR
276 Like GENSIO_CONTROL_LADDR but gets the remote addresses on a gensio.
277 The gensio may need to be open. This is only implemented on bottom-
278 level gensios, like serialdev, network interfaces, echo, file, ipmisol,
279 etc.
280 GENSIO_CONTROL_RADDR_BIN
282 Return the binary remote address for the given gensio. Only imple‐
283 mented for network gensios and pty.
284 GENSIO_CONTROL_LPORT
286 Return the local port for the connection. Only for network connec‐
287 tions. This is useful if you pass in "0" for the port to let the OS
288 chose; you can get the actual port chosen.
289 GENSIO_CONTROL_CLOSE_OUTPUT
291 Close writing to the gensio, but leave reading along. This is only for
292 stdio gensios; it lets you close stdin to the subprogram without af‐
293 fecting the subprogram's stdout.
294 GENSIO_CONTROL_CONNECT_ADDRESS_STR
296 Return the address the connection was made to. For SCTP. gen‐
297 sio_raddr_to_str() returns all the remote addresses in SCTP's current
298 state. This will return the addresses that the original connectx was
299 done to.
300 GENSIO_CONTROL_REMOTE_ID
302 Return some sort of remote id for what is on the other end of the con‐
303 nection. Not implemented for most gensios, only for getting the pid on
304 a pty and stdio and the file descriptor on serialdev.
305 GENSIO_CONTROL_AUX_DATA
307 Return auxiliary sent on the connection. On certauth, this will be
308 sent to the remote end and be available for them.
309 GENSIO_CONTROL_REM_AUX_DATA
311 Return auxiliary received from the other end of the connection. On
312 certauth, this will be received from the remote end.
313 GENSIO_CONTROL_IOD
315 Used to get the IOD pointer for the gensio as a raw pointer. For gen‐
316 sios that have more than one IOD, the string you pass in will be a
317 string number representing which IOD, "0" for the first (stdin), "1"
318 for the second (stdout), and "2" for the third, (stderr).
319 GENSIO_CONTROL_EXTRAINFO
321 This enables extra info to be returned on a received UDP packet. If
322 this is set to non-zero (normal string like "1" passed in), extra
323 fields will be added to the auxdata in received packets. These field
324 are: "daddr:<address>" with the destination address from the packet and
325 "ifidx:<n>" with the integer interface index the packet was received
326 on.
327 GENSIO_CONTROL_ENABLE_OOB
329 Out of band (OOB) data is disabled by default on all gensios and set‐
330 ting this to non-zero (normal string like "1" passed in) will enable
331 it. Note that you should only set this on the gensio you are directly
332 communicating with, it is used between some gensios.
333 GENSIO_CONTROL_WIN_SIZE
335 For pty gensios, sets the window size of the virtual window. The value
336 is a string with four values separated by ":". The first two are the
337 number of rows and number of columns. The second two are number of
338 horizontal pixels and number of vertical pixels. The pixel values are
339 currently ignored by windows. pixel values do not have to be given, if
340 there are less than 4 values, pixels values are ignored and set to
341 zero. datalen is ignored.
342 GENSIO_CONTROL_START_DIR
344 For pty and stdio gensios (that start another program), this will cause
345 the new program to run in the given directory instead of the current
346 directory.
347 GENSIO_CONTROL_IN_RATE , GENSIO_CONTROL_OUT_RATE
349 For sound gensios, return the sample rate for the gensio for input or
350 output.
351 GENSIO_CONTROL_IN_BUFSIZE , GENSIO_CONTROL_OUTBUFSIZE
353 For sound gensios, return the buffer size in bytes for input our out‐
354 put. The data will be delivered to upper layer in chunks of this size.
355 GENSIO_CONTROL_IN_NR_CHANS , GENSIO_CONTROL_OUT_NR_CHANS
357 For sound gensios, return the number of channels for the interface for
358 input or output.
359 GENSIO_CONTROL_IN_FORMAT , GENSIO_CONTROL_OUT_FORMAT
361 For sound gensios, return the format of the user data. Like "float",
362 "int16be", etc.
363 GENSIO_CONTROL_DRAIN_COUNT
365 The amount of data left to be transmitted. For sound, this is in
366 frames.
367 SERIAL PORT CONTROLS
369 The following set various serial port values.
370 On the client these set the value or request the value from the other
372 end. When getting the data value is not used. When setting the data
373 value is a string with a number or setting. The response in the done
374 callback reports a string with the set value (which may be different
375 than the requested value) in the same format as the request.
376 On the server these are used to respond to a client event. The done
378 callback is ignored.
379 GENSIO_ACONTROL_SER_BAUD
381 is the baud rate as a number. For instance, setting to "1200" sets
382 1200 baud. Not all gensio support all baud rates.
383 GENSIO_ACONTROL_SER_DATASIZE
385 is the datasize, a number from "5" to "8". Not all gensio support all
386 data sizes.
387 GENSIO_ACONTROL_SER_PARITY
389 sets the parity, one of "none", "odd", "even", "mark" or "space". You
390 can use gensio_parity_to_str and gensio_str_to_parity to convert be‐
391 tween the string and numeric values. gensio_parity_to_str returns NULL
392 if the number isn't value, gensio_str_to_parity returns -1 if the
393 string is not valid.
394 GENSIO_ACONTROL_SER_STOPBITS
396 sets the number of stop bits, "1", or "2".
397 GENSIO_ACONTROL_SER_FLOWCONTROL
399 sets the flow control type, one of "none", "xonxoff", or "rtscts". You
400 can use gensio_flowcontrol_to_str and gensio_str_to_flowcontrol to con‐
401 vert between the string and numeric values. gensio_flowcontrol_to_str
402 returns NULL if the number isn't value, gensio_str_to_flowcontrol re‐
403 turns -1 if the string is not valid.
404 GENSIO_ACONTROL_SER_IFLOWCONTROL
406 sets the input flow state, one of "none", "dcd", "dtr", or "dsr". You
407 use the same conversion functions as GENSIO_ACONTROL_SER_FLOWCONTROL
408 for converting between strings and integers.
409 GENSIO_ACONTROL_SER_SBREAK
411 Enables or disables the break condition on a serial port. One of "on"
412 or "off". You can use gensio_onoff_to_str and gensio_str_to_onoff to
413 convert between the string and numeric values. gensio_onoff_to_str re‐
414 turns NULL if the number isn't value, gensio_str_to_onoff returns -1 if
415 the string is not valid.
416 GENSIO_ACONTROL_SER_DTR
418 Enables or disables the DTR line on a serial port. One of "on" or
419 "off". See GENSIO_ACONTROL_SER_SBREAK for string/integer conversions.
420 GENSIO_ACONTROL_SER_RTS
422 Enables or disables the RTS line on a serial port. One of "on" or
423 "off". See GENSIO_ACONTROL_SER_SBREAK for string/integer conversions.
424 GENSIO_ACONTROL_SER_CTS
426 Enables or disables the CTS line on a serial port. One of "on" or
427 "off". ipmisol only. See GENSIO_ACONTROL_SER_SBREAK for string/inte‐
428 ger conversions.
429 GENSIO_ACONTROL_SER_DCD_DSR
431 Enables or disables the DCD and DTR lines on a serial port. One of
432 "on" or "off". ipmisol only. See GENSIO_ACONTROL_SER_SBREAK for
433 string/integer conversions.
434 GENSIO_ACONTROL_SER_RI
436 Enables or disables the RI line on a serial port. One of "on" or
437 "off". ipmisol only. See GENSIO_ACONTROL_SER_SBREAK for string/inte‐
438 ger conversions.
439 GENSIO_ACONTROL_SER_SIGNATURE
441 Fetches or reports the rfc2217 signature for a serial port. This is an
442 arbitrary string. telnet only.
443 SERIAL PORT REPORT MASKS
446 These set (on the client) the mask used to monitor various lines on a
447 serial ports. The bits set will be the ones reported in the corre‐
448 sponding events. These are numbers in strings, you bitwise or the val‐
449 ues together.
450 GENSIO_CONTROL_SER_MODEMSTATE
452 sets the modem control lines that are reported. Values to or together
453 are: GENSIO_SER_MODEMSTATE_CTS, GENSIO_SER_MODEMSTATE_DSR, GEN‐
454 SIO_SER_MODEMSTATE_RI, GENSIO_SER_MODEMSTATE_CD.
455 GENSIO_CONTROL_SER_LINESTATE
457 sets the line states (errors) that are reported. Values to or together
458 are: GENSIO_SER_LINESTATE_DATA_READY, GENSIO_SER_LINESTATE_OVERRUN_ERR,
459 GENSIO_SER_LINESTATE_PARITY_ERR, GENSIO_SER_LINESTATE_FRAMING_ERR, GEN‐
460 SIO_SER_LINESTATE_BREAK, GENSIO_SER_LINESTATE_XMIT_HOLD_EMPTY, GEN‐
461 SIO_SER_LINESTATE_XMIT_SHIFT_EMPTY, GENSIO_SER_LINESTATE_TIMEOUT_ERR.
462 OTHER SERIAL PORT OPERATIONS
465 This is a set of other operations that can be performed on a serial
466 port.
467 GENSIO_CONTROL_SER_FLOWCONTROL_STATE
469 GENSIO_CONTROL_SER_FLUSH
471 requests a flush of the input or output queues, values are "recv",
472 "xmit", or "both".
473 GENSIO_CONTROL_SER_SEND_BREAK
475 requests a serial break (of arbitrary length) be sent. The value is
476 not used.
477
480 Zero is returned on success, or a gensio error on failure.
481
483 gensio_err(3), gensio(5)
484 27 Feb 2019 gensio_control(3)