1gensio(5)                     File Formats Manual                    gensio(5)
2
3
4

NAME

6       gensio - How to specify a gensio
7

SYNOPSIS

9       <type>[(options)][,gensio|terminaloptions]
10

DESCRIPTION

12       gensio stands for GENeral Stream Input Output.  It provides an abstrac‐
13       tion for all kinds of stream I/O, and even makes some packet  I/O  look
14       like  stream  I/O  (like  UDP).  In particular, gensio makes it easy to
15       create encrypted and authenticated connections.
16
17       The gensio library specifies a connection (gensio) using a string  for‐
18       mat.   This consists of a gensio type, optional options in parenthesis.
19       For a terminal gensio (one that is at the bottom of the stack), it  may
20       take  more  options separated by a comma.  For filter gensios (ones not
21       on the bottom of the stack) another gensio must be specified after  the
22       comma.  For instance:
23
24              serialdev,/dev/ttyS0
25
26       specifies a serial port gensio.  Or:
27
28              tcp(readbuf=100),localhost,4000
29
30       specifies  a  TCP connection with a 100 byte read buffer, to connect to
31       port 4000 on localhost.  Or:
32
33              telnet,tcp,localhost,4000
34
35       specifies a telnet filter on top of a TCP connection.
36
37       When specifying a gensio, you can add quotes (single or double) to  re‐
38       move the special meaning for some characters, so you can have commas in
39       options and such.  They may also be escaped with a "\".  For  instance,
40       if  you are specifying a laddr in an sctp address, you need to do this.
41       The following address:
42
43              sctp(laddr=localhost,4001),localhost,3023
44
45       will result in a failure because the option splitting code  will  split
46       at the commas.  Instead, do:
47
48              sctp(laddr="localhost,4001"),localhost,3023
49
50       and it will work.
51
52       Accepter gensios, gensios used for accepting connections, as opposed to
53       connecting gensios, are specified in the  same  way.   Each  individual
54       type  can  vary, and some gensios are only connecting gensios.  The op‐
55       tions can vary from the accepter and connecting  gensios  of  the  same
56       type.   For  instance,  an accepting TCP gensio does not have to have a
57       hostname, but a connecting one does.
58
59       When an accepter gensio receives a connection, it will  create  an  ac‐
60       cepted gensio.  This works mostly like a connecting gensio, except some
61       functions may be limited.  You may not be able to close and  then  open
62       an accepted gensio.
63
64       The  gensio  library  has a concept of client and server.  The accepted
65       gensios are generally considered servers.  Connecting gensios are  gen‐
66       erally  considered clients.  Some gensios may allow this to be overrid‐
67       den.
68
69       A gensio may be reliable or not.  A reliable gensio will  reliably  de‐
70       liver  all  data in sequence, like TCP.  An gensio that is not reliable
71       may drop data or deliver data out of sequence, like UDP.  This  can  be
72       queried with gensio_is_reliable().
73
74       A  gensio  may be packet or not.  A packet gensio will exactly match up
75       writes and reads.  So if you write 15 bytes into one side,  a  15  byte
76       read for that data will appear on the other side.  A gensio that is not
77       packet will not respect write boundaries, that 15 byte write may result
78       in  multiple  reads  or it may be combined with another write into more
79       than 15 bytes.  Packet I/O requires careful use to make  it  work  cor‐
80       rectly.   If  the  gensio doesn't have room for another packet, a write
81       will succeed but write 0 bytes.  Otherwise if you write larger  than  a
82       packet  size, it will only take the number of bytes that can fit into a
83       packet, so it will truncate.  This is useful if you want to stream over
84       a  packet  interface,  but  if you really want packets you have to make
85       sure all the sizes are set properly. Particularly, you must set the max
86       read and write size to the same value.  You should check on writes that
87       it wrote all the data.  You can do partial read handling, if you  like,
88       but  you will only get the rest of the packet on the second and follow‐
89       ing read.
90
91       A gensio may be message oriented.  This implementation is  stolen  from
92       SCTP  (even  though  it's not really supported on Linux at the moment).
93       It basically means you can  explicitly  mark  message  boundaries  when
94       sending data, and that explicit mark will be set on the read side.  You
95       do this by adding an "eom" auxdata on the write; the end of that  write
96       it  assumed  to  be the end of a message.  If the write does not accept
97       all the data, the "eom" is ignored, you must write the  remaining  data
98       again  with  "eom"  set.  You may also do partial write of messages and
99       set "eom" at the end.  On the receive side, "eom" will be set when  the
100       end of a message is delivered.  The data delivered in the receive call‐
101       back will be only the data for that message.  If the user does not  ac‐
102       cept  all  the data, the data left in the message is again presented to
103       the user with "eom" set.
104
105       The options vary greatly between the different  gensios.   Each  gensio
106       type  will  be  covered  in  a separate section.  Also note that gensio
107       types can be dynamically added by the user, so  there  may  be  gensios
108       available that are not described here.
109
110       Unless otherwise noted, every gensio takes a:
111
112
113       readbuf=<n>
114              option to specify the read buffer size.
115

DEFAULTS

117       Every option to a gensio (including the serialdev and ipmisol options),
118       unless othersize stated, is available as a  default  for  the  gensios.
119       You  can  use gensio_set_default() to set the default value used by all
120       gensios allocated after that point.  If you leave the  class  NULL,  it
121       will  set  the  base default, which will affect all gensios unless they
122       have an override.  If you set the class, it will  only  affect  gensios
123       with that class name.
124
125       Be  very  careful  with some defaults.  Setting "mode" default, for in‐
126       stance, could really screw things up.
127
128       For string defaults, setting the default value to NULL causes the  gen‐
129       sio to use it's backup default.
130

Serial gensios

132       Some gensio types support serial port setting options.  Standard serial
133       ports, IPMI Serial Over LAN, and telnet with RFC2217 enabled.
134
135       A client serial gensio can set and get serial port  options  using  the
136       sergensio_xxx() functions.  Server serial gensios receive requests from
137       the client via GENSIO_EVENT_SER_xxx events in the callback.
138

Streams and Channels

140       Some gensios support the concept of a stream and/or a channel.
141
142       A stream is delivered as part of the normal data stream  of  a  gensio.
143       The  "default" stream will be treated normally.  All other streams will
144       have "stream=<x>" given in the auxdata to specify which stream to write
145       on  or which stream was read from.  Streams cannot be individually flow
146       controlled.
147
148       A channel is a flow of data like a stream, but it can  be  individually
149       flow   controlled.    It   appears   as   a  new  gensio  in  the  GEN‐
150       SIO_EVENT_NEW_CHANNEL callback.  You can create  a  channel  with  gen‐
151       sio_alloc_channel()  and then open it with gensio_open().  Once open, a
152       channel works like a normal gensio.  If you close the main channel  for
153       a gensio, the other channels will stay open; the resources for the main
154       channel will still be kept around until all channels are closed.
155
156       See the indvidual gensio description for more  information  on  streams
157       and channels.
158

PUBLIC KEY CRYPTOGRAPHY

160       The ssl and certauth gensios use public key cryptography.  This section
161       gives a little overview of how that works.  You can  safely  skip  this
162       section if you already understand these concepts.
163
164       Public key cryptography is used to authenticate and encrypt information
165       at the beginning of a session.  It is a fairly expensive operation  and
166       is not generally used to encrypt information after the beginning.
167
168       In public key cryptography, you have three basic things: A private key,
169       a certificate (or public key), and a certificate authority (CA).
170
171       The private key is just that: private.  You don't even send  your  pri‐
172       vate  key  to  a certificate authority for signing of your certificate.
173       Keep it private, non-readable by everyone else.  Protect it, if it  be‐
174       comes  known your certificate becomes useless to you, anyone can imper‐
175       sonate you.
176
177       The certificate is the public key,  and  is  mathematically  associated
178       with  a  single private key.  It's just that, public, anyone can use it
179       to test that you have the private key by asking you to sign some  data.
180       The  data in the certificate (like the Common Name) is part of the cer‐
181       tificate.  If that data is modified, the  certificate  validation  will
182       fail.
183
184       The  CA is generally a trusted third-party that validates you and signs
185       your certificate (generally for a fee).  CAs  issue  their  own  public
186       certificates  that  are well-known and generally available on your sys‐
187       tem.  The CA certificates are used to prove that  your  certificate  is
188       valid.
189
190   SIGNING
191       The  process  if signing has been mentioned already, but not described.
192       Basically, you use your private key to generate a value over some given
193       data  that proves you have the private key.  The certificate is ised to
194       mathematically verify the signature.
195
196       Two things are normally done with this:
197
198       In a public key exchange, the entity wishing to be authorized  sends  a
199       certificate.   The  authorizing  entity will look through it's CA for a
200       certificate that has signed the sent certificate.  If  the  authorizing
201       entity  finds  a certificate that can be used to validate the sent cer‐
202       tificate, the sent certificate is valid.
203
204       After that, the authorizing entity sends some generally random data  to
205       the  other  entity.  The other entity will take that data, perhaps some
206       other important data that it want to make sure is not modified  in  the
207       transfer,  and signs that data.  It sends the signature back to the au‐
208       thorizing entity.  The authorizing entity can then use the data and the
209       signature to validate that the sending entity has the private key asso‐
210       ciated with the certificate.
211
212       This is basically how https works.  Note it is the web client that  au‐
213       thenticates the web server, not the other way around.  This proves that
214       you are connecting to the entity you say you are  connecting  to.   The
215       authentication  of a web client to the web server is generally done via
216       a different mechanism (though SSL/TLS used by the ssl gensio has a  way
217       to do it, it is not generally used for that purpose).
218
219       In  the  web server scenario, data in the certificate (specifically the
220       Common Name and Subject Alternate Name) must match the name of the  web
221       page  to which you are connecting.  The ssl and certauth gensios do not
222       do this authentication, that is up to the user if it is necessary.
223
224   ENCRYPTING
225       The certificate can be used to encrypt data that can only be  decrypted
226       with  the private key.  When establishing an encrypted connection, this
227       is generally used to transfer a symmetric cryptography key from one en‐
228       tity to another (the authorizing entity to the requesting entity in the
229       case above).  You could encrypt all the data with the public  key,  but
230       that  is very expensive and in our example above would require certifi‐
231       cates and private keys on both ends.
232
233   SELF-SIGNED CERTIFICATES
234       It is possible to create a certificate that can act as its own certifi‐
235       cate  authority.   This is how ssh works.  You create a public and pri‐
236       vate key.  You put the public key in the .ssh/authorized_keys directory
237       on  systems where you want to log in.  The certificate acts as both the
238       public key (as part of the initial transfer) and the CA (in the  autho‐
239       rized_key directory) for authorizing you use of the system you are log‐
240       ging in to.
241
242       ssh also stores places it has connected to in  .ssh/known_hosts,  which
243       is  the  CA  in the opposite direction.  This is why it asks you if you
244       have never connected to a system before, it doesn't have the key in its
245       CA.   Or  why,  if you connect to a system you have connected to before
246       and the certificates don't match or fail validation, it complains about
247       it.
248
249       So if you are using self-signed certificates, you need to be careful to
250       put only ones you trust in the CA.  This is obviously not possible in a
251       large  system like the world wide web, thus the creation of third-party
252       trusted CAs.
253
254   TRUST AND CRYPTOGRAPHY
255       The above discussions mention trust several times.   Cryptography  does
256       not  remove  the  need for trust.  It just makes trust more convenient.
257       If someone sends you a certificate, you need to validate  that  it  was
258       actually  them that sent you the certificate, and that it was not modi‐
259       fied in transit.  If you add that  certificate  to  your  CA,  you  are
260       trusting  the certificate, and you better make sure (with fingerprints,
261       generally, see the openssl docs  for  details)  that  it  came  from  a
262       trusted entity.
263
264       The  hardest part of cryptography in general is key management.  Break‐
265       ing cryptographic algorithms is really hard.  Getting people to divulge
266       private keys or use the wrong keys is a lot easier.
267
268       For  more on cryptography in general, and cryptography and trust, Bruce
269       Schneier has some excellent books on the subject.
270

IPv6, IPv4, and host names

272       Note that a single hostname may result in more than one  address.   For
273       instance, it may have both an IPv4 and IPv6 address.  These are treated
274       just like multiple hostnames.  For instance, if you use localhost as  a
275       host name, you generally get the IPv4 and IPv6 version:
276
277              $ gensiot -a -p tcp,localhost,1234
278              Address 0(0): ipv6,::1,1234
279              Address 1(0): ipv4,127.0.0.1,1234
280
281       The  hostname  may  be prefixed with ipv4 or ipv6, which will force the
282       connections to those protocols.  Specifying ipv6n4 will create a socket
283       that is IPv6 but will handle IPv4 connections.
284
285       Note  that  using ipv6n4 will not automatically create a socket that is
286       available to IPv4.  You can do, say  tcp,ipv6n4,::1,1234  and  it  will
287       work,  but  since  ::1 is not IPv4, you won't be able to get to it from
288       IPv4.    You   have    to    specify    an    IPv4    address,    like:
289       tcp,ipv6n4,127.0.0.1,1234  which  will  result  in a single IPv6 socket
290       mapped into IPv4 space:
291
292              $ gensiot -a -p tcp,ipv6n4,localhost,1234
293              Address 0(0): ipv6,::ffff:127.0.0.1,1234
294
295       If you  do  not  specify  a  hostname  on  an  accepting  gensio  (like
296       sctp,1234)  it  will  only  create  an IPv6 socket that is IPv4 mapped.
297       This way it will accept both IPv4 and IPv6  connections.   Even  though
298       getaddrinfo  would  normally return two addresses, only the IPv6 one is
299       used unless there are no IPv6 addresses configured where it will return
300       an IPv4 address.
301
302       In general, for connecting gensios only the first address that is found
303       will be used.  SCTP is the exception, it will do  multi-homing  on  all
304       the addresses that come up.  Do you may need to be fairly specific with
305       addresses.
306
307       In general IPv6 addresses are preferred if both are available.
308

gtime

310       Time consists of a set of numbers each followed  by  a  single  letter.
311       That  letter may be 'D', 'H', 'M', 's', 'm', 'u', or 'n', meaning days,
312       hours, minutes, seconds, milliseconds,  microseconds,  or  nanoseconds.
313       So,  for  instance,  "10D5H4M9s100u" would be ten days, 5 hours, 4 min‐
314       utes, 9 seconds, 100 microseconds.  If a plain number with no letter at
315       the  end is given, the value may default to a specific unit.  That will
316       be specified by the specific gensio.
317

TCP

319       tcp[(<options>)][,<hostname>],<port>[[,<hostname>],<port>[...]]
320       hostname = [ipv4|ipv6|ipv6n4,]<name>
321
322       A TCP connecting gensio must have  the  hostname  specified.   Multiple
323       hostname/port  pairs  may  be  specified.  For a connecting TCP gensio,
324       each one will be tried in sequence until a connection  is  established.
325       For  acceptor  gensios, every specified hostname/port pair will be lis‐
326       tened to.
327
328   Dynamic Ports
329       For accepters, if the port is specified as zero, a random port  in  the
330       dynamic  port range specified by IANA will be chosen.  If more than one
331       address is present, the same port will be  chosen  for  all  addresses.
332       You can fetch the port using the gensio_acc_control() function with the
333       option GENSIO_ACC_CONTROL_LPORT.
334
335
336   Out Of Band Data
337       TCP supports out of band (oob) data, which is data that will be  deliv‐
338       ered  out  of  order as soon as possible.  This comes in a normal read,
339       but with "oob" in the auxdata.  You can send oob data by  adding  "oob"
340       to  the write auxdata, but oob writes are limited to 1 byte and writing
341       any more than this results in undefined behavior.  Note  that  "oobtcp"
342       is also delivered and accepted in auxdata, so you can tell TCP oob data
343       from other oob data.
344
345   Options
346       In addition to readbuf, the tcp gensio takes the following options:
347
348       nodelay[=true|false]
349              Sets nodelay on the socket.
350
351       laddr=<addr>
352              An address specification to bind to on the local socket  to  set
353              the local address.
354
355       reuseaddr[=true|false]
356              Set SO_REUSEADDR on the socket, good for accepting gensios only.
357              Defaults to true.
358
359       tcpd=on|print|off
360              Accepter only, sets tcpd handling on the socket.  If "on",  tcpd
361              is  enforced and the connection is just closed on a tcpd denial.
362              "print" is like on, except it  writes  "Access  Denied"  on  the
363              socket  before  closing it.  "off" disabled tcpd handling on the
364              socket.  Defaults to on.  Not available if tcpd is  disabled  at
365              compile time.
366
367       tcpdname=<name>
368              Accepter  only,  sets  the  name to use for tcpd access control.
369              This defaults to "gensio", and the  default  can  be  overridden
370              with  gensio_set_progname().  This option allows you to override
371              it on a per-gensio accepter basis.  Not  available  if  tcpd  is
372              disabled at compile time.
373
374   Remote Address String
375       The  remote  address  will be in the format "[ipv4|ipv6],<addr>,<port>"
376       where the address is in numeric format, IPv4, or IPv6.
377
378   Remote Address
379       TCP returns a standard  struct  sockaddr  for  GENSIO_CONTROL_RADDR_BIN
380       control.
381
382   Direct Allocation
383       Allocated  as  a  terminal  gensio  with  gdata as a "const struct gen‐
384       sio_addr *"
385

UDP

387       udp[(<options>)][,<hostname>],<port>[[,<hostname>],<port>[...]]
388       hostname = [ipv4|ipv6|ipv6n4,]<name>
389
390       A UDP gensio creates a UDP socket, but it makes it look like  an  unre‐
391       aliable stream of data.  The specification is the same as a TCP socket,
392       except that a UDP socket is created, obviously.
393
394       The semantics of a UDP socket are a little bit strange.   A  connecting
395       UDP socket is fairly straightforward, it opens a local socket and sends
396       data to the remote socket.
397
398       An accepter gensio is not so straightforward.  The accepter gensio will
399       create  a new accepted gensio for any packet it receives from a new re‐
400       mote host.  If you disable read on any of the accepted gensio  or  dis‐
401       able  accepts  on  the  accepting gensio, it will stop all reads on all
402       gensios associated with that accepting gensio.
403
404       Note that UDP accepter gensios are not really required for  using  UDP,
405       the  are  primarily there for handling ser2net accepter semantics.  You
406       can create two connecting UDP gensios and communicate between them.
407
408       UDP gensios are not reliable, but are obviously packet-oriented.
409
410       Port 0 is supported just like TCP for accepters, see Dynamic  Ports  in
411       the TCP section above for details.
412
413       The  destination  address  defaults  to the one specified on the gensio
414       specifier (for connecting gensios) or the remote address that initiated
415       the  connection  (for  accepting  gensios), but may be overridden using
416       "addr:<addr>" in the write auxdata.
417
418   Options
419       In addition to readbuf, the udp gensio takes the following options:
420
421       laddr=<addr>
422              An address specification to bind to on the local socket  to  set
423              the local address.
424
425       nocon[=true|false]
426              Don't  be  connection oriented, just receive all packets and de‐
427              liver them without establishing connections.  Only valid for the
428              client  gensio.   The receive address is passed into the auxdata
429              prefixed by "addr:", this  is  the  address  formatted  by  gen‐
430              sio_addr_to_str().
431
432       mloop[=true|false]
433              If  false, multicast packets transmitted will not be received on
434              the local host.  If true, they will.
435
436       mttl=[1-255]
437              Set the multicast time-to-live value.  The default is 1, meaning
438              multicast stays in the local network.  Increasing this value in‐
439              creases the number of hops over multicast routers a send  packet
440              will traverse.
441
442       mcast=<addr>
443              Add  an  address  to  receive multicast packets on.  There is no
444              port number, this is just addresses.  You can  specify  multiple
445              addresses  in a single multicast option and/or the multicast op‐
446              tion can be used multiple times to add  multiple  multicast  ad‐
447              dresses.
448
449       reuseaddr[=true|false]
450              Set  SO_REUSEADDR on the socket, good for connecting and accept‐
451              ing gensios.  Defaults to false.
452
453   Remote Address String
454       The remote address will be in  the  format  "[ipv4|ipv6],<addr>,<port>"
455       where the address is in numeric format, IPv4, or IPv6.
456
457   Remote Address
458       UDP  returns  a  standard  struct sockaddr for GENSIO_CONTROL_RADDR_BIN
459       control.
460
461   UDP Multicast
462       Multicast can be used on UDP gensios with the nocon,  maddr  and  laddr
463       options.  To set up a multicast, create a client UDP gensio and set the
464       laddr for the receive port and the destination address to the multicast
465       and enable nocon, like:
466
467              "udp(mcast='ff02::1',laddr='ipv6,3000',nocon),ff02::1,3000"
468
469       and you will receive and send data on the multicast address.  The laddr
470       option is required to set the port to receive on.  It  means  you  will
471       have a local address, too, and will receive packets on that, too.
472
473   Direct Allocation
474       Allocated  as  a  terminal  gensio  with  gdata as a "const struct gen‐
475       sio_addr *"
476

SCTP

478       sctp[(<options>)][,<hostname>],<port>[[,<hostname>],<port>[...]]
479       hostname = [ipv4|ipv6|ipv6n4,]<name>
480
481       An SCTP gensio is specified like a UDP or TCP one.  However, the seman‐
482       tics are different.  For a connecting gensio, it will attempt to create
483       a multi-homed connect with all the specified hostnames and ports.   All
484       the ports must be the same.
485
486       For  an  accepter  gensio,  it will create a single socket with all the
487       specified addresses as possible destinations.   Again,  all  the  ports
488       must be the same.
489
490       SCTP  gensios  are  reliable.  They are not, at the moment, packet ori‐
491       ented.  There is currently no support of SCTP_EXPLICIT_EOR in the Linux
492       implementation  of  SCTP,  and without that it would be hard to make it
493       packet oriented.
494
495       When specifying IPv6 addresses that might map  to  IPv4,  you  must  be
496       careful.   If one side can do IPv4 and the other side can only do IPv6,
497       the connection may come up, but will disconnect quickly because it can‐
498       not  communicate  on  the  IPv4  side.  For instance, the following ac‐
499       cepter:
500
501              tools/gensiot -a "sctp,ipv6,::,1234"
502
503       and the following connector:
504
505              tools/gensiot "sctp,::1,1234"
506
507       will fail this way because the connector will support IPv4 add but  the
508       accepter will not.
509
510   Nagle and SCTP
511       SCTP  implements  the  Nagle  algorithm  by default, which can interact
512       badly if sack_freq is set to more than one.  At  least  Linux  defaults
513       sack_freq  to  2, but the gensio overrides this to avoid surprising be‐
514       haviour.  What happens is in some situations you can get an outstanding
515       packet that is unacked, since sack_freq is greater than one.  The Nagle
516       algorithm will not send any new data until any  already  sent  data  is
517       acked.   So one end is waiting for a new packet to send a sack, and the
518       other end is holding data until it gets a sack.  So you get stuck wait‐
519       ing  for the sack_delay where the sack will go out and kick things back
520       off again.
521
522       You need to be aware of this if you modify sack_freq.
523
524   Options
525       In addition to readbuf, the sctp gensio takes the following options:
526
527       instreams=<n>
528
529       ostreams=<n>
530              These specify the number of incoming and  outgoing  streams  for
531              the connection.  The default is one.  The stream is given in the
532              auxdata for read and write in the format "stream=<n>".
533
534       sack_freq=<n>
535
536       sack_delay=<n>
537              These  specify  the  handling  of   selective   acknowledgements
538              (sacks).   sack_freq sets the number of outstanding packets that
539              must be received before sending a sack.  The default is 1, mean‐
540              ing  it  doesn't  wait at all.  sack_delay sets the maximum time
541              before a sack is sent if outstanding  packets  are  present,  in
542              milliseconds.   The  default  is  10,  but  this  is disabled if
543              sack_freq is set to 1.  Setting either of these to 0 enables the
544              system defaults.
545
546       nodelay[=true|false]
547              Sets nodelay on the socket.
548
549       laddr=<addr>
550              An  address  specification to bind to on the local socket to set
551              the local address.
552
553       reuseaddr[=true|false]
554              Set SO_REUSEADDR on the socket, good for accepting gensios only.
555              Defaults to true.
556
557              Port  0  is  supported  just like TCP for accepters, see Dynamic
558              Ports in the TCP section above for details.
559
560              SCTP support out of band (oob) data, which is data that will  be
561              delivered  out  of  order  as soon as possible.  This comes in a
562              normal read, but with "oob" in the auxdata.  You  can  send  oob
563              data by adding "oob" to the write auxdata.
564
565              See documentation on SCTP for more details.
566
567   Remote Address String
568       The      remote      address      will     be     in     the     format
569       "[ipv4|ipv6],<addr>,<port>[;[ipv4|ipv6],<addr>,<port>[...]]"  where the
570       address  is  in numeric format, IPv4, or IPv6.  Each remote address for
571       the SCTP connection is listed.
572
573   Remote Address
574       SCTP returns a packed struct sockaddr for GENSIO_CONTROL_RADDR_BIN con‐
575       trol, per SCTP semantics.
576
577   Direct Allocation
578       Allocated  as  a  terminal  gensio  with  gdata as a "const struct gen‐
579       sio_addr *"
580

UNIX

582       unix[(<options>)],<socket_path>
583
584       Create a unix domain socket as an accepter, or connect to a unix domain
585       socket as a connecter.
586
587       A  file  will be created with the given socket path, you must have per‐
588       missions to create a writeable file in that location.  If the file  al‐
589       ready  exists,  an  error will be returned on an accepter socket unless
590       you specify delsock which will cause the file to be deleted.
591
592       You should read the unix(7) man page for details on  the  semantics  of
593       these sockets, especially permissions.  The options below allow setting
594       various permission and ownership of the file, but this may not have any
595       effect  on  who  can  open socket depending on the particular operating
596       system.  Portable programs should not rely on these permissions for se‐
597       curity.   Also note that Linux remote credentials are not currently im‐
598       plemented.
599
600   Options
601       In addition to readbuf, the unix gensio takes the following options:
602
603       delsock[=true|false]
604              If the socket path already exists, delete it before opening  the
605              socket.
606
607       umode=[0-7|[rwx]*]
608              Set  the  user  file mode for the unix socket file.  This is the
609              usual read(4)/write(2)/execute(2) bitmask per  chmod,  but  only
610              for  the  user portion.  If a mode is specified, all other modes
611              default to "6" (rw) +unless they are specified,  and  the  final
612              mode  is modified by the umask +per standard *nix semantics.  If
613              no mode is specified, it is set to +the default  and  not  modi‐
614              fied.  Note that the perm option below is +probably a better way
615              to set this.
616
617       gmode=[0-7|[rwx]*]
618              Set the group file mode for the unix socket file, see umode  for
619              details.
620
621       omode=[0-7|[rwx]*]
622              Set  the  other file mode for the uix socket file, see umode for
623              details.
624
625       perm=[0-7][0-7][0-7]
626              Set the full mode for the unix socket file per standard *nix se‐
627              mantics, modified by umask as the above mode operations are.
628
629       owner=<name>
630              Set the owner of the unix socket file to the given user.
631
632       group=<name>
633              Set the group of the unix socket file to the given group.
634
635   Remote Address String
636       The remote address will be: "unix,<socket path>".
637
638   Remote Address
639       UNIX returns a standard struct sockaddr_un for GENSIO_CONTROL_RADDR_BIN
640       control.
641
642   Direct Allocation
643       Allocated as a terminal gensio with  gdata  as  a  "const  struct  gen‐
644       sio_addr *"
645

serialdev

647       serialdev[(<options>)],<device>[,<serialoption>[,<serialoption>]]
648
649       A  serialdev  connection  is  a  local  serial  port.   The device is a
650       /dev/xxx type, and should be real stream device of some type that  nor‐
651       mal  termios or serial processing work on.  For non-serial devices, use
652       the "dev" gensio.
653
654       This is, no surprise, a serial gensio.
655
656       You can also use "sdev" instead of "serialdev" for shorthand.
657
658       One problem with serialdev and UUCP locking is that  if  you  fork()  a
659       process  while  one is open, the forked process will have the serialdev
660       but the value in the UUCP lockfile will be incorrect.  There's not much
661       that can be done about this, so be careful.
662
663   Options
664       In  addition  to  readbuf, the serialdev gensio takes the following op‐
665       tions:
666
667       uucplock[=true|false]
668              Enable or disable UUCP locking on the device.   The  default  is
669              true  for  everything  except pty devices and /dev/tty.  This is
670              ignored on systems that don't support this.
671
672       flock[=true|false]
673              Enable or disable flock locking on the device.  The  default  is
674              true  for  everything except /dev/tty.  Note that this does both
675              an "flock(fd, LOCK_EX | LOCK_NB)" and an  "ioctl(fd,  TIOCNXCL)"
676              to  lock the device.  This is ignored on systems that don't sup‐
677              port this.
678
679       drain_time=off|<time in 100ths of a second>
680              The total amount of time to wait for the data to be sent on  the
681              serial port at close time.  Close will be delayed this amount of
682              time, or until all the data is  transmitted.   Default  is  off.
683              When  setting  the default value for this, "off" will not be ac‐
684              cepted, use -1 instead.
685
686       char_drain_wait=off|<time in 100ths of a second>
687              At close time, if this much time elapses  and  no  character  is
688              sent,  finish the close.  Default is 50 (.5 seconds).  Note that
689              if both this and drain_time are off, if the serial port is  hung
690              on  flow control, it will never close.  When setting the default
691              value for this, "off" will not be accepted, use -1 instead.
692
693       wronly[=true|false]
694              Set   the   device   to   write   only.    Default   is   false.
695              rdonly[=true|false]  Set  the  device  to read only.  Default is
696              false.
697
698   Serialoptions
699       There are a plethora of serialoptions, available as defaults:
700
701       [speed=]<speed><parity><databits><stopbits>
702              This is a normal serial port configuration  specification,  like
703              "9600N81".   The  "speed="  at  the  beginning  is optional, but
704              "speed" is a default type for this.
705
706       wronly[=true|false]
707              This option is deprecated, use the "dev" gensio  for  non-serial
708              port devices and the wronly option in the parameters.
709
710              Set  the device to write only.  No termios definition is done on
711              the port.  This can be done to talk to a line printer port,  for
712              instance.   False  by default.  Note that for historical reasons
713              this is different than the wronly option set in the  parameters,
714              this one sets both turns off termio process and sets wronly.
715
716       nobreak[=true|false]
717              Clear  the  break line at start (or don't clear it).  Default it
718              to not clear it (false).
719
720       rs485=off|<delay     rts     before     send>:<delay     rts      after
721       send>[:<conf>[:<conf>]]
722              Set up RS-485 for the serial port.  The first two parameters set
723              the RTS delay (in milliseconds) of RTS before and after sending.
724              The  conf  values  can be: "rts_on_send" - RTS set when sending,
725              "rts_after_send" - RTS set after sending, "rx_during_tx"  -  can
726              receive and transmit at the same time, and "terminate_bus" - en‐
727              able bus termination.
728
729              Using "off" will disable rs485; that is useful for overriding  a
730              user-defined default setting.  Default is "off".
731
732       xonxoff[=true|false]
733              Enable/disable xon/xoff flow control.  Default is false.
734
735       rtscts[=true|false]
736              Enable/disable rts/cts flow control.  Default is false.
737
738       local[=true|false]
739              Ignore/don't  ignore the modem control lines.  The default it to
740              not ignore them (false).  However, if you don't ignore the modem
741              control lines, it can result in long shutdown delays.
742
743       dtr[=on|off]
744              Force  the  DTR  line to be on or off when the gensio is opened.
745              Note that the order of the dtr and rts options  matter.   Which‐
746              ever  comes first in the options will be set first.  This can be
747              useful if the lines need to be sequenced in a certain order  for
748              the piece of hardware involved.
749
750       rts[=on|off]
751              Force  the  RTS  line to be on or off when the gensio is opened.
752              See the dtr section above for notes on ordering of lines.
753
754       hangup-when-done[=true|false]
755              Lower/don't lower the modem control lines  when  the  gensio  is
756              closed.   The  default  is  not modify the value.  On Unix, this
757              will modify HUPCL value set on the termios after close,  because
758              there's no other real way to do that.  On Windows, it will clear
759              DTR and RTS on close.
760
761              On the default for this, it's a integer, -1 means don't set  the
762              value, 0 means turn off, 1 means turn on.
763
764       custspeed[=true|false]
765              Allow/don't allow setting of custom baud rates.  Ignored if cus‐
766              tom baud rates are not supported.  Normally only  standard  baud
767              rates  are  supported  (1200,  2400,  etc).  If supported by the
768              hardware, this allows any arbitrary value to be set.
769
770   Remote Address String
771       The remote address string is the device and serial parms, in  a  format
772       like  "9600N81[,<option>[,<option>[...]]]".   Options are one of: XONX‐
773       OFF, RTSCTS, CLOCAL, HANGUP_WHEN_DONE, RTSHI, RTSLO, DTRHI, DRLO,  off‐
774       line.
775
776   Remote ID
777       The  remote ID for the serial dev is the file descriptor returned as an
778       integer.
779
780   Direct Allocation x
781       Allocated as a terminal gensio with gdata as a "const char *" with  the
782       device and parameters string.
783

dev

785       dev[(<options>)],<device>  This is like a serialdev gensio, but doesn't
786       do any serial port processing like termios or break  processing.   This
787       can  be  used for /dev/lpX devices for instance.  This is read/write by
788       default, you must set the wronly option to disable read  access  for  a
789       write-only  device and rdonly to disable write access for read-only de‐
790       vices.
791
792       This takes the same options as serialdev except that  it  does  not  do
793       locking.   The  drain_time  and  char_drain_wait options may or may not
794       work.  It does not take serial options.
795

stdio

797       accepter = stdio[(options)]
798       connecting = stdio[(options)],<program>
799
800       The stdio gensio is a fairly strange one, but it's fairly useful.
801
802       A connecting stdio gensio runs the given program (unless self is set as
803       an  option)  and connects its standard input and output to the gensio's
804       main channel.  So it's easy to run a program and interact with it.   If
805       you  want  to  get  stderr  from the gensio, open a channel on the main
806       channel gensio, see below.
807
808       NOTE: Though epoll() doesn't work with normal files, the  stdio  gensio
809       has  special  handling  for normal files so they mostly work.  This can
810       have surprising side effects if you use stdin as a normal  file.   When
811       you  hit the end of stdin, the stdio gensio will return GE_REMCLOSE and
812       you may shut down the gensio and possibly lose any output going to std‐
813       out.  Use the file gensio if you can.
814
815       For  connecting  gensios,  in the forked process, the code will set the
816       effective (and saved) uid and guid to the current real uid and guid  if
817       the effective and real uids are different.  This way a user can set the
818       real uid and gid to what they want the program to run under,  but  keep
819       the  effective uid and gid to the (probably root) values so they can be
820       restored to those values after opening the pty.  The group list is also
821       set  to the groups the real userid is in.  Note that nothing is done if
822       the effective and real userids are the same.
823
824       If you have both stdin/stdout and stderr opened, you must close both of
825       them to completely close the gensio.  You cannot re-open the gensio un‐
826       til both are closed.
827
828       The connecting gensio support the GENSIO_CONTROL_ENVIRONMENT control to
829       allow the environment to be set for the new process.
830
831       An accepting gensio immediately does a connection when started and con‐
832       nection stdin and stdout of the running program to the gensio.
833
834   Options
835       In addition to readbuf, a connecting stdio takes the following options:
836
837       self[=true|false]
838              Instead of starting a program, connect to the running  program's
839              stdio.   This  is  the same as an accepting stdio gensio, except
840              you don't have to go through the accept process.
841
842       console[=true|false]
843              Like self, except connect to the running program's  console  de‐
844              vice,  /dev/tty  on  Unix and CONIN$/CONOUT$ on Windows.  Useful
845              for reading passwords and such.
846
847       start-dir=path
848              Start the subprogram in the given path instead  of  the  current
849              directory.
850
851       raw[=true|false]
852              For  a  "self",  console, or accepter version of the gensio, put
853              the I/O in "raw" mode, meaning character at a time, turn off ^C,
854              etc.  This will fail on pipes or files.
855
856       stderr-to-stdout
857              Send  standard  error output to standard out instead of having a
858              separate channel for it.
859
860       noredir-stderr
861              Do not modify the stderr for the program, use the  calling  pro‐
862              gram's  stderr.   This  can  be useful if you want to see stderr
863              output from a program.
864
865   Channels
866       The stdio connecting gensio that start another program does not provide
867       stderr  as part of the main gensio. You must create a channel with gen‐
868       sio_alloc_channnel() and then open it get stderr output.  The args  for
869       gensio_alloc_channel()  may be an optional "readbuf=<num>" and sets the
870       size of the input buffer.
871
872   Remote Address String
873       The remote address string is either "stdio,<args>" for the main channel
874       or  "stderr,<args>"  for  the error channel.  The args will be a set of
875       quoted strings with a space between each string, one for each argument,
876       with '"' around each argument, each '"' in the string converted to '\"'
877       and each '\' in the string converted to '\\'.
878
879   Remote ID
880       The remote ID is the pid for the remote  device,  only  for  connecting
881       gensios that start a program, not for any other type.
882
883   Direct Allocation
884       Allocated  as  a  terminal  gensio  with gdata as a "const char * const
885       args[]" for the gensio.  gdata is not used for the accepter.
886

echo

888       connecting = echo[(options)]
889
890       The echo gensio just echos back all the data written to it.  Useful for
891       testing.
892
893   Options
894       In addition to readbuf, a connecting echo takes the following options:
895
896       noecho[=true|false]
897              Instead of echoing the data, just become a data sink.
898
899       data=<str>
900              Supply  the  given  data  as the data to be read.  When combined
901              with noecho, it will create a  gensio  that  just  supplies  the
902              given data then returns a GE_REMCLOSE when done.
903
904   Remote Address String
905       The remote address string is "echo".
906
907   Direct Allocation
908       Allocated as a terminal gensio, gdata is not used.
909

file

911       connecting = file[(options)]
912
913       The  file  gensio  opens an (optional) input file and (optional) output
914       file for the gensio.  If you need to read/write a file in  gensio,  you
915       must  use  this.   Semantics  on files for stdio do not alway work cor‐
916       rectly.
917
918       If an input file is specified, data will be read from  the  input  file
919       and  delivered  on  the read interface of the gensio until end of file,
920       when the GE_REMCLOSE error will be returned.
921
922       If an output file is specified, data will be written to the output file
923       on writes.  The output file is always ready to receive data.
924
925   Options
926       In addition to readbuf, a connecting file takes the following options:
927
928       infile=filename
929              Set the input filename.
930
931       outfile=filename
932              Set the output filename.
933
934       read_close[=true|false]
935              If this is true (the default), cause a GE_REMCLOSE error on read
936              when all the file data is ready.  If false, just stop  returning
937              data  and  don't do the GE_REMCLOSE.  This is useful if you just
938              want to inject a bunch of data then do nothing.
939
940       create[=true|false]
941              Create the output file if it does not exist.  Ignored for read.
942
943       append[=true|false]
944              Open the file in append mode.  If  not  specified,  it  will  be
945              opened  at  the  beginning  of  the file and if writing, it will
946              overwrite.  Ignored for read.
947
948       trunc[=true|false]
949              Truncate the file on open.  All data will be  deleted  from  the
950              file when opened.  Ignored for read.
951
952       binary[=true|false]
953              Open  the file in binary mode.  This is ignored on *nix systems,
954              but for Windows it affects how newlines are handled.
955
956       umode=[0-7|[rwx]*]
957              Set the user file mode for the file  if  the  file  is  created.
958              This is the usual read(4)/write(2)/execute(2) bitmask per chmod,
959              but only for the user portion.  If  a  mode  is  specified,  all
960              other  modes default to "6" (rw) +unless they are specified, and
961              the final mode is modified by the umask +per standard  *nix  se‐
962              mantics.  If no mode is specified, it is set to +the default and
963              not modified.  Note that the perm option below  is  +probably  a
964              better way to set this.
965
966       gmode=[0-7|[rwx]*]
967              Set the group file mode for the file if the file is created, see
968              umode for details.
969
970       omode=[0-7|[rwx]*]
971              Set the other file mode for the file if the file is created, see
972              umode for details.
973
974       perm=[0-7][0-7][0-7]
975              Set the full mode for the file per standard *nix semantics, mod‐
976              ified by umask as the above mode operations are.
977
978   Remote Address String
979       The remote address string is "file([infile=<filename][,][outfile=<file‐
980       name>])".
981
982   Direct Allocation
983       Allocated as a terminal gensio, gdata is not used.
984

dummy

986       accepter = dummy
987
988       The  dummy gensio accepter is useful for place holding, where you don't
989       want a real working accepter but need to put something.
990
991       As you might guess, it doesn't do anything.
992
993   Direct Allocation
994       Allocated as a terminal gensio, gdata is not used.
995

ipmisol

997       ipmisol[(options)],<openipmi arguments>[,ipmisol option[,...]]
998
999       An ipmisol gensio creates an IPMI Serial Over LAN connection to an IPMI
1000       server.   See  the  OpenIPMI documentation for information on the argu‐
1001       ments.
1002
1003       This is a serial gensio, but the baud rate settings are fairly limited.
1004
1005   Options
1006       In addition to readbuf, the ipmisol gensio takes the following options:
1007
1008       writebuf=<n>
1009              to set the size of the write buffer.
1010
1011       It also takes the following ipmisol options:
1012
1013       9600, 19200, 38400, 57600, 115200
1014              Baud rate, 9600 by default.  Anything after the  number  is  ig‐
1015              nored, for compatibility with things like "N81".  You cannot set
1016              those values for ipmisol, they are fixed at "N81".
1017
1018       nobreak[=true|false]
1019              Disable break processing.  False by default.
1020
1021       authenticated[=true|false]
1022              Enable or disable authentication.  True by default.
1023
1024       encrypted[=true|false]
1025              Enable or disable encrypted.  True by default.
1026
1027       deassert-CTS-DCD-DSR-on-connect[=true|false]
1028              False by default
1029
1030       shared-serial-alert=fail|deferred|succeed
1031              Behavior of handling serial alerts.  fail by default.
1032
1033       ack-timeout=<number>
1034              The time (in microseconds) when an ack times  out.   1000000  by
1035              default.
1036
1037       ack-retries=<number>
1038              The number of times (ack-timeouts) an ack is re-sent before giv‐
1039              ing up.  10 by default.
1040
1041   Direct Allocation
1042       Allocated as a terminal gensio with gdata as a "const char *".
1043

telnet

1045       accepter = telnet[(options)]
1046       connecting = telnet[(options)]
1047
1048       A telnet gensio is a filter that sits on top  of  another  gensio.   It
1049       runs the standard telnet protocol andn support RFC2217.
1050
1051   Options
1052       In addition to readbuf, the telnet gensio takes the following options:
1053
1054       writebuf=<n>
1055              set the size of the write buffer.
1056
1057       rfc2217[=true|false]
1058              enable  or disable RFC2217 mode for this gensio.  If this is en‐
1059              abled and the remote end  of  the  connection  supports  RFC2217
1060              also,  the  gensio will be set up as a serial gensio and you can
1061              do normal serial gensio handling on it.
1062
1063       winsize[=true|false]
1064              enable or disable RFC1073, window size change notification.  De‐
1065              fault is false.
1066
1067       mode=client|server
1068              Set  the  telnet  mode to client or server.  This lets you run a
1069              telnet server on a connecting gensio, or a telnet client  on  an
1070              accepter gensio.
1071
1072   Remote info
1073       telnet passes remote id, remote address, and remote string to the child
1074       gensio.
1075

ssl

1077       accepter = ssl[(options)]
1078       connecting = ssl[(options)]
1079
1080       An SSL gensio runs the SSL/TLS protocol on top of another gensio.  That
1081       gensio must be reliable.
1082
1083       Use  is  pretty  straightforward.  The hardest part about using the SSL
1084       gensio is the certificates.  A server SSL gensio must be given  a  cer‐
1085       tificate  and  a  key.  A client SSL gensio must be given a certificate
1086       authority.  A client will user the certificate authority to verify that
1087       the server has the proper certificate and keys.
1088
1089       The  gensio has options to have the server request the certificate from
1090       the client and validate it.
1091
1092       SSL gensios are reliable.  They are also packet-oriented.
1093
1094   Options
1095       In addition to readbuf, the SSL gensio takes the following options:
1096
1097       writebuf=<n>
1098              set the size of the write buffer.
1099
1100       CA=<filepath>
1101              Set a place to look for certificates for authorization.  If this
1102              ends in a "/", then this is expected to be a directory that con‐
1103              tains files with certificates that must be  hashed  per  OpenSSL
1104              (see  the "openssl rehash" command for details.  Otherwise it is
1105              a single file that contains one or more certificates.   The  de‐
1106              fault  CA path is used if not specified.  Note that setting this
1107              to an empty string disables it, so you can  override  a  default
1108              value if necessary.
1109
1110       key=<filename>
1111              Specify the file to get the private key for the server.  This is
1112              required for servers.  It may be specified for clients,  and  is
1113              required for the client if the server requires a certificate (it
1114              has CA set).
1115
1116       cert=<filename>
1117              Specify the file that contains the certificate used for the con‐
1118              nection.   If this is not specified, the certificate is expected
1119              to be in the key file.  Note  that  setting  this  to  an  empty
1120              string  disables it, so you can override a default value if nec‐
1121              essary.
1122
1123       mode=client|server
1124              Normally an accepter gensio is in server mode and  a  connecting
1125              gensio  is in client mode.  This can be used to switch the roles
1126              and run in SSL server mode  on  a  connecting  gensio,  or  vice
1127              versa.
1128
1129       con-timeout=<gtime>
1130              Set  the  timeout  for a connection to complete.  If the connect
1131              process does not complete in this amount of time, the connection
1132              will  be  dropped.   The default is 60 seconds.  See the "gtime"
1133              section for more info on how to set the time.  Note that the de‐
1134              fault  setting  for con-timeout is not a gtime, it is an integer
1135              in seconds.
1136
1137       clientauth[=true|false]
1138              Normally a client is not authorized by  the  server.   This  re‐
1139              quires that the client provide a certificate and authorizes that
1140              certificate.  Ignored for client mode.
1141
1142       allow-authfail[=true|false]
1143              Normally if the remote end certificate is  not  valid,  the  SSL
1144              gensio  will close the connection.  This open allows the open to
1145              succeed with an invalid or missing certificate.  Note  that  the
1146              user  should  verify  that  authentication  is  set  using  gen‐
1147              sio_is_authenticated().
1148
1149              Verification of the common name is not  done.   The  application
1150              should  do this, it can fetch the common name and other certifi‐
1151              cate data through a control interface.
1152
1153              You can use self-signed certificates in this interface.  Just be
1154              aware  of  the  security  ramifications.   This gensio is fairly
1155              flexible, but you must use it carefully to have a secure  inter‐
1156              face.
1157
1158              The  SSL  gensio will call the gensio event callback (client) or
1159              the gensio acceptor event callback (server) after  the  certifi‐
1160              cate  is  received  but  before  it  is  validated with the GEN‐
1161              SIO_EVENT_PRECERT_VERIFY   or    GENSIO_ACC_EVENT_PRECERT_VERIFY
1162              events.  This allows the user to validate data from the certifi‐
1163              cate (like common name)  with  GENSIO_CONTROL_GET_PEER_CERT_NAME
1164              or  set  a  certificate  authority  for the validation with GEN‐
1165              SIO_CONTROL_CERT_AUTH.
1166
1167   Remote info
1168       ssl passes remote id, remote address, and remote string  to  the  child
1169       gensio.
1170

certauth

1172       accepter = certauth[(options)]
1173       connecting = certauth[(options)]
1174
1175       A  certauth gensio runs an authentication protocol to on top of another
1176       gensio.  That gensio must be reliable and encrypted.
1177
1178       This is like the reverse of SSL.  The client has a key and certificate,
1179       the  server has a certificate authority (CA).  This also supports pass‐
1180       word authentication.
1181
1182       Once authentication occurs, this gensio acts  as  a  passthrough.   The
1183       readbuf option is not available in the gensio.
1184
1185   Options
1186       The certauth gensio takes the following options:
1187
1188       CA=<filepath>
1189              Set a place to look for certificates for authorization.  If this
1190              ends in a "/", then this is expected to be a directory that con‐
1191              tains  files  with certificates that must be hashed per OpenSSL,
1192              see the gensio-keygen(1) in  the  rehash  section  for  details.
1193              Otherwise it is a single file that contains one or more certifi‐
1194              cates.  The default CA path for openssl is used  if  not  speci‐
1195              fied.   This  is  used  on  the  server  only,  it is ignored on
1196              clients.  Note that setting this to an empty string disables it,
1197              so you can override a default value if necessary.
1198
1199       key=<filename>
1200              Specify the file to get the private key for the client.  This is
1201              required for clients.  It is ignored on server.
1202
1203       cert=<filename>
1204              Specify the file to get the private key for the client.  This is
1205              required  for clients.  It is ignored on server.  If this is not
1206              specified, the certificate is expected to be in  the  key  file.
1207              Note  that  setting  this to an empty string disables it, so you
1208              can override a default value if necessary.
1209
1210       username=<name>
1211              Specify a username to authenticate with on the remote end.  This
1212              is required for the client.  It is ignored on the server.
1213
1214       service=<string>
1215              Set  the  remote service requested by the client.  Optional, but
1216              the other end may reject the connection if it is  not  supplied.
1217              Ignored on the server.
1218
1219       password=<string>
1220              Specify  the  password to use for password authentication.  This
1221              is not recommended, the callback is more secure to use.
1222
1223       mode=client|server
1224              Normally an accepter gensio is in server mode and  a  connecting
1225              gensio  is in client mode.  This can be used to switch the roles
1226              and run in server mode on a connecting gensio, or vice versa.
1227
1228       allow-authfail[=true|false]
1229              Normally if the remote end certificate is not  valid,  the  cer‐
1230              tauth  gensio  will  close the connection.  This open allows the
1231              open to succeed with an invalid or  missing  certificate.   Note
1232              that  the  user  should  verify that authentication is set using
1233              gensio_is_authenticated().
1234
1235       use-child-auth[=true|false]
1236              If the child gensio is authenticated, then do not run the proto‐
1237              col, just go straight into passthrough mode and don't do any au‐
1238              thentication.
1239
1240       enable-password[=true|false]
1241              On the server, allow passwords for login.  On the client, send a
1242              password  if  asked for one.  By default passwords are disabled.
1243              Use of passwords is much less secure than certificates, so  this
1244              is discouraged.
1245
1246       enable-2fa[=true|false]
1247              On  the  server,  request  2-factor authentication data from the
1248              client.  This is only useful for situations where  the  2-factor
1249              data is known before startup, like Google Authenticator or other
1250              things of that nature.  It is not useful for text/email types of
1251              things  that  send  the  data after the connection is initiated.
1252              But those are usually interactive and can be handled with inter‐
1253              active methods.
1254
1255       2fa=<string>
1256              On the client, provide the given 2-factor authentication data to
1257              the server if it asks for it.
1258
1259       Verification of the common name is not done.  The application should do
1260       this, it can fetch the common name and other certificate data through a
1261       control interface.  It may also use the username  fetched  through  the
1262       control interface.
1263
1264       con-timeout=<gtime>
1265              Set  the  timeout  for a connection to complete.  If the connect
1266              process does not complete in this amount of time, the connection
1267              will  be  dropped.   The default is 60 seconds.  See the "gtime"
1268              section for more info on how to set the time.  Note that the de‐
1269              fault  setting  for con-timeout is not a gtime, it is an integer
1270              in seconds.
1271
1272              You can use self-signed certificates in this interface.  Just be
1273              aware  of  the  security  ramifications.   This gensio is fairly
1274              flexible, but you must use it carefully to have secure authenti‐
1275              cation.
1276
1277              The certauth gensio has 4 major callbacks dealing with authenti‐
1278              cation of the user.  They may or may not be called depending  on
1279              the  circumstances.  The normal events come in if you have allo‐
1280              cated a gensio and are doing an open.  The _ACC_ events come  in
1281              if  it  is  coming  in from an accept and there is no gensio re‐
1282              ported yet.  In the _ACC_ case, be careful, do not use the given
1283              gensio for anything but checking certificate and username param‐
1284              eters, and do not save it.
1285
1286              All these calls should return 0 if they want the  authentication
1287              to  immediately succeed, EKEYREJECTED if they reject the authen‐
1288              tication, ENOTSUP if they want certauth to ignore that  part  of
1289              the  authentication,  or any other errno will result in the con‐
1290              netion being shut down.
1291
1292              The callbacks are:
1293
1294       GENSIO_EVENT_AUTH_BEGIN / GENSIO_ACC_EVENT_AUTH_BEGIN
1295              On the server side, this is called when to authentication is re‐
1296              quested  buy  the client.  The username will be available if the
1297              user provided it via GENSIO_CONTROL_USERNAME.
1298
1299       GENSIO_EVENT_PRECERT_VERIFY / GENSIO_ACC_EVENT_PRECERT_VERIFY
1300              On the server side, thi is called after the certificate has been
1301              received  but  before  it is verified.  The user can use this to
1302              query the certificate and update the certificate authority based
1303              on username or certificate information.
1304
1305       GENSIO_EVENT_VERIFY_PASSWORD / GENSIO_ACC_EVENT_VERIFY_PASSWORD
1306              On  the server side, this is called if the certificate verifica‐
1307              tion has failed and after the password has been  requested  from
1308              the  remote end.  The password is passed in, it is cleared imme‐
1309              diately after this call.
1310
1311       GENSIO_EVENT_REQUEST_PASSWORD / GENSIO_ACC_EVENT_REQUEST_PASSWORD
1312              On the client side, this is called if the server requests that a
1313              password  be  sent  and  the password is not already set for the
1314              gensio.  The requested password is immediately cleared after be‐
1315              ing sent to the server.
1316
1317   Remote info
1318       certauth  passes  remote  id,  remote address, and remote string to the
1319       child gensio.
1320

mux

1322       accepter = mux[(options)]
1323       connecting = mux[(options)]
1324
1325       A mux gensio is a gensio filter that allows one or more channels to  be
1326       created  on  top of a single gensio, multiplexing the connection.  Each
1327       channel has full individual flow-control.   The  channels  are  message
1328       oriented  as  described above, and use can use a mux without additional
1329       channels to just do message demarcation.   They  also  support  out-of-
1330       bounds messages.
1331
1332   Options
1333       A mux gensio takes the following options:
1334
1335       max_channels=<n>
1336              Allow  at  most  <n> channels to be created in the mux.  The de‐
1337              fault is 1000.  The minimum value of <n> is 1,  the  maximum  is
1338              65536.
1339
1340       service=<string>
1341              Set  the  remote service requested by the client.  Optional, but
1342              the other end may reject the connection if it is  not  supplied.
1343              Ignored on the server.
1344
1345       mode=client|server
1346              By  default  a mux accepter is a server and a mux connecter is a
1347              client.  The protocol is mostly symmetric, but it's hard to kick
1348              things off properly if both sides try to start things.  This op‐
1349              tion lets you override the default mode in case  you  have  some
1350              special need to do so.
1351
1352       When  the  open is complete on the mux gensio, it will work just like a
1353       transparent filter with message demarcation.  In effect, you  have  one
1354       channel open.
1355
1356   Creating Channels
1357       To  create  a  channel, call the gensio_alloc_channel() function on the
1358       mux gensio.  This will return a new gensio that is a channel on the mux
1359       gensio.   You can pass in arguments, which is an array of strings, cur‐
1360       rently readbuf, writebuf, and service are accepted.   The  service  you
1361       set  here  will be set on the remote channel so the other end can fetch
1362       it.  The new channel needs to be opened with  gensio_open()  before  it
1363       can be used.
1364
1365       As  you  might  imaging, the other end of a mux needs to know about the
1366       new channel.  If one end (either end, doesn't matter) calls  gensio_al‐
1367       loc_channel()  and then opens the new channel, the other end will get a
1368       GENSIO_EVENT_NEW_CHANNEL event as described in the Streams and Channels
1369       section.   You can call it using any mux channel.  The first element in
1370       the auxdata is the service.
1371
1372       You can modify the service value after you allocate the channel but be‐
1373       fore you open it.
1374
1375   Out Of Band Messages
1376       mux  support  out of band (oob) data, which is data that will be deliv‐
1377       ered normally.  This comes in a normal read, but with "oob" in the aux‐
1378       data.  You can send oob data by adding "oob" to the write auxdata.  You
1379       should normally use the "eom" flag so the end of the out of  band  mes‐
1380       sages ismarked.
1381
1382       This  is  so you can send special data outside of the normal processing
1383       of data.
1384
1385   Mux Events
1386       As you might imaging, normal data events come through the gensio  chan‐
1387       nel they are associated with.  Close events will, too.  If a mux gensio
1388       closes abnormally (like the underlying connection fails) you will get a
1389       read error on each channel.
1390
1391       New  channel events (and other global events coming from lower gensios,
1392       like if you are running over ssl or telnet) come in through the  origi‐
1393       nal gensio normally.  However, you can close that, another channel will
1394       be chosen to receive those event.  In general, it's best to handle  the
1395       global events on all channels and not assume.
1396
1397   Closing and Freeing a Mux
1398       To  close  a  mux  gensio,  just close all channels associated with it.
1399       There is no global close mechanism (you would not believe the  complex‐
1400       ity  that adds).  Once you have closed a mux gensio, you can re-open it
1401       with gensio_open().  It will not recreate all the channels for you, you
1402       will  have  one  channel, and the channel you use to call gensio_open()
1403       will become the first channel.
1404
1405       You cannot re-open individual channels.
1406
1407       To free a mux gensio, you must free all the channels on it.
1408

pty

1410       connecting = pty[(options)][,<program>]
1411
1412       Create a pty and optionally run a program on the other end of it.  With
1413       a  program  specified,  this  is sort of like stdio, but the program is
1414       running on a terminal.  Only connection gensios are supported.
1415
1416       pty has some unusual handling to allow execution  of  login  shells  of
1417       users from root.
1418
1419       In  Unix type systems, if the first character of the program is '-', it
1420       is removed from the execution of the command but left in argv[0].  This
1421       will cause a shell to act as a login shell.
1422
1423       On  Unix type systems, in the forked process, the code will set the ef‐
1424       fective (and saved) uid and guid to the current real uid  and  guid  if
1425       the effective and real uids are different.  This way a user can set the
1426       real uid and gid to what they want the program to run under,  but  keep
1427       the  effective uid and gid to the (probably root) values so they can be
1428       restored to those values after opening the pty.  The group list is also
1429       set  to the groups the real userid is in.  Note that nothing is done if
1430       the effective and real userids are the same.
1431
1432       On Windows, the new process is set to the user in the impersonation to‐
1433       ken  if  it is set.  In that case, the new process will be run in a new
1434       process group.  If no impersonation token is set, the new process  will
1435       run  as  the  user  of calling process in the same process group as the
1436       calling process.
1437
1438       The pty gensio supports the GENSIO_CONTROL_ENVIRONMENT control to allow
1439       the  environment  to  be  set for the new process.  GENSIO_CONTROL_ARGS
1440       sets the arguments as an argv array.  GENSIO_CONTROL_WIN_SIZE sets  the
1441       terminal  size in characters.  GENSIO_CONTROL_START_DIR sets the direc‐
1442       tory the new process runs in.
1443
1444       If no program is specified, when the pty gensio is opened it will  just
1445       create  the  pty  but won't attach anything to it.  Another program can
1446       open the pty.  You can get the slave pty device by  getting  the  local
1447       address string.
1448
1449   Options
1450       In  addition  to  readbuf,  the pty gensio takes the following options.
1451       These options are only allowed if the pty  is  unattached.   ptys  with
1452       programs run on them need to follow the standard semantics.
1453
1454       link=<filename>
1455              create  a symbolic link from filename to the pty name.  This way
1456              you can have a fixed reference to refer to  the  pty.   Standard
1457              permissions  apply.   Without  forcelink  the  open will file if
1458              filename already exists.  Unix only.
1459
1460       forcelink[=true|false]
1461              if link is specified, if a file already exists  where  the  sym‐
1462              bolic  link  is, replace it.  Be careful, it deletes whatever is
1463              there indiscriminately.
1464
1465       start-dir=path
1466              Start the subprogram in the given path instead  of  the  current
1467              directory.
1468
1469       raw[=true|false]
1470              causes the pty to be set in raw mode at startup.  This is impor‐
1471              tant for anything that will start  writing  immediately  to  the
1472              pty.   If  you don't set this, echo will be on and writes on the
1473              master will be echoed back.  In general, this is useful for  un‐
1474              attached ptys.  It was added for testing, but will be usedful in
1475              many situations.
1476
1477       umode=[0-7|[rwx]*]
1478              Set the user file mode for the pty slave.   This  is  the  usual
1479              read(4)/write(2)/execute(2)  bitmask per chmod, but only for the
1480              user portion.  If a mode is specified, all other  modes  default
1481              to  "6"  (rw)  +unless they are specified, and the final mode is
1482              modified by the umask +per standard *nix semantics.  If no  mode
1483              is  specified, it is set to +the default and not modified.  Note
1484              that the perm option below is +probably  a  better  way  to  set
1485              this.
1486
1487       gmode=[0-7|[rwx]*]
1488              Set  the  group  file  mode for the pty slave, see umode for de‐
1489              tails.
1490
1491       omode=[0-7|[rwx]*]
1492              Set the other file mode for the pty slave,  see  umode  for  de‐
1493              tails.
1494
1495       perm=[0-7][0-7][0-7]
1496              Set the full mode for the pty per standard *nix semantics, modi‐
1497              fied by umask as the above mode operations are.
1498
1499       owner=<name>
1500              Set the owner of the slave pty to the given user.
1501
1502       group=<name>
1503              Set the group of the slave pty to the given group.
1504
1505       user=<name>
1506              Windows only, create the process under the given user instead of
1507              the  calling  process'  user.   This  generally required special
1508              privileges.
1509
1510       passwd=<name>
1511              Windows only, user must be specified to use.  Log  on  the  user
1512              with the given password.  If a password is not given, an S4U lo‐
1513              gon will be attempted, but that may not work  so  well  as  some
1514              things are missing from the access token of the user.
1515
1516              NOTE: There are significant security issues with passing a pass‐
1517              word this way.  You must use  proper  password  handling.   mod‐
1518              ule=<name>  Windows only, user must be specified to use.  Create
1519              the new user token with the given  module.   If  not  specified,
1520              "gensio" is used.
1521
1522   Remote Address String
1523       The  remote  address  string  the program and arguments run on the pty.
1524       The argiuments will be a set of quoted strings  with  a  space  between
1525       each string, one for each argument, with '"' around each argument, each
1526       '"' in the string converted to '\"' and each '\'  in  the  string  con‐
1527       verted to '\\'.
1528
1529   Remote Address
1530       The address is a pointer to an integer, the ptym file descriptor is re‐
1531       turned.  addrlen must be set to sizeof(int) when passed in.
1532
1533   Local Address String
1534       This returns the device of the pty, generally  /dev/pts/<n>.   This  is
1535       useful  for pty gensios with no program, it allows you to get the value
1536       for the other end to connect to.  Note that if you close and re-open  a
1537       pty gensio, you may be a different local address string.
1538
1539   Direct Allocation
1540       Allocated  as  a  terminal  gensio  with gdata as a "const char * const
1541       args[]".
1542

msgdelim

1544       accepter = msgdelim[(options)]
1545       connecting = msgdelim[(options)]
1546
1547       A message delimiter converts an unreliable stream (like a serial  port)
1548       into  an unreliable packet interface.  This is primarily to allow a re‐
1549       liable packet interface like relpkt to run on top of a serial port.  It
1550       does not support streaming of data, so it's not very useful by itself.
1551
1552       Messages  are  delimited with a start of message and end of message and
1553       have a CRC16 on the end of them.
1554
1555       This is primarily for use on serial ports and other  streams  that  can
1556       munge up the data.  Use the mux gensio for TCP and such.
1557
1558       The default buffer size is 128 bytes, which is ok for a reasonably fast
1559       serial port interface.
1560
1561   Options
1562       In addition to readbuf, the msgdelim gensio  takes  the  following  op‐
1563       tions:
1564
1565       writebuf=<n>
1566              set the size of the write buffer.
1567
1568       crc[=on|off]
1569              Enable/disable  the CRC at the end of the packet.  Useful if you
1570              are running over a reliable protocol, and especially for testing
1571              relpkt so you can fuzz it and bypass the crc errors.
1572

relpkt

1574       accepter = relpkt[(options)]
1575       connecting = relpkt[(options)]
1576
1577       Converts  an unreliable packet interface (currently only UDP and msgde‐
1578       lim) into a reliable packet interface.  This lets you have  a  reliable
1579       connection over a serial port (with msgdelim) or UDP.
1580
1581       Note  that  UDP  is not recommended, it doesn't handle flow control and
1582       such in a friendly manner.
1583
1584       relpkt is unusual in dealing with clients and servers.  The protocol is
1585       symmetric,  for  the most part, you can start two clients and they will
1586       connect to each other, if they are started relatively close in time  to
1587       avoid  one timing out.  A relpkt server will simply wait forever for an
1588       incoming connection on an open.
1589
1590       relpkt does not support readbuf.  It supports the following:
1591
1592       max_pktsize=<n>
1593              Sets the maximum size of a packet.  This may be reduced  by  the
1594              remote end, but will never be exceeded.  This must be at least 5
1595              bytes shorter than the maximum packet size of the interface  be‐
1596              low  it.   This  defaults to 123 (msgdelim max packet size - 5).
1597              If run over UDP, this should probably be increased  for  perfor‐
1598              mance.
1599
1600       max_packets=<n>
1601              Sets the maximum number of outstanding packets.  This may be re‐
1602              duced by the remote end, but will never be exceeded.
1603
1604       mode=client|server
1605              By default a relpkt is a server on an accepter and a client on a
1606              connecter.  See the discussion above on clients and servers.
1607
1608       timeout=<gtime>
1609              Specify  the  time for a timeout.  If relpkt sends a message re‐
1610              quiring an ack, it will wait  this  long  before  resending  the
1611              packet.  See the "gtime" section for more info on how to set the
1612              time.  If you don't specify a time modifier, the default  is  in
1613              seconds.  The default is one second.
1614
1615       max_timeouts=<n>
1616              The maximum number of timeouts before giving up on a connection.
1617              The default is 5.
1618

ratelimit

1620       accepter = ratelimit[(options)]
1621       connecting = ratelimit[(options)]
1622
1623       Limit the transmit rate of data going through this  filter  gensio.   A
1624       number  of  bytes  is  let  through, then transmit is delayed until the
1625       given delay has passed.  Receive is not  currently  rate  limited,  but
1626       that may be added in the future.
1627
1628       xmit_len=<n>
1629              The  number of bytes to allow before a delay.  Note that the de‐
1630              lay occurs after a single write succeeds, so if a single byte is
1631              written  it  will  delay.   If a write is done of more than this
1632              length, it will be limited to this length.  Defaults to one.
1633
1634       xmit_delay=<gtime>
1635              The amount of time to wait between writes.  See the "gtime" sec‐
1636              tion  for information for this time specification.  This must be
1637              supplied.
1638

trace

1640       accepter = trace[(options)]
1641       connecting = trace[(options)]
1642
1643       A transparent gensio that allows the data passing through it to be sent
1644       to a file.  Useful for debugging.  It can also block data in either di‐
1645       rection.
1646
1647       Note that the trace gensio only prints data that  is  accepted  by  the
1648       other end.  So, for instance, if the trace gensio receives 100 bytes of
1649       read data, it will deliver it immediately to the gensio above  it.   If
1650       that  only  accepts  40  bytes, trace will only print 40 bytes and will
1651       only accept 40 bytes from the gensio below it.  Same for sent data.
1652
1653   Options
1654       trace does not support readbuf.  It supports the following options:
1655
1656       dir=none|read|write|both
1657              Sets what data is traced.  "none" means no data is  traced  (the
1658              default),  "read"  traces data flowing up the gensio stack (read
1659              by the parent), write traces data flowing down the gensio  stack
1660              (written by the parent), and "both" traces reads and writes.
1661
1662       block=none|read|write|both
1663              Blocks  data in one or both directions.  "none" means data flows
1664              both directions (the default), "read" means data flowing up  the
1665              gensio  stack  is  discarded,  write means data flowing down the
1666              gensio stack is discarded, and "both" discards  both  reads  and
1667              writes.  Data that is discarded is not traced.
1668
1669       raw[=yes|no]
1670              If  set,  traced data will be written as raw bytes.  If not set,
1671              traced data will be written in human-readable form.
1672
1673       file=<filename>
1674              The filename to write trace data to.  If not  supplied,  tracing
1675              is  disabled.  Note that unless delold is specified, the file is
1676              opened append, so it will add new trace data onto the end of  an
1677              existing file.
1678
1679       stderr[=yes|no]
1680              Send the trace output to standard error.  Overrides file.
1681
1682       stdout[=yes|no]
1683              Send  the  trace  output to standard output.  Overrides file and
1684              stderr.
1685
1686       delold[=yes|no]
1687              Delete the old data in the file  instead  of  appending  to  the
1688              file.
1689

perf

1691       accepter = perf[(options)]
1692       connecting = perf[(options)]
1693
1694       A  gensio  for  measuring throughput for a connection.  This allows the
1695       performance of a connection to be measured.  It does not pass any  data
1696       through.   Instead, it writes raw data to the lower layer (if write_len
1697       is set) and reads data from the lower layer,  counting  the  bytes  and
1698       measuring the time.
1699
1700       To the upper layer, perf prints out statistics about the data transfer.
1701       It prints out the number of bytes written and read each second, and  at
1702       the end it prints a total.
1703
1704       If write_len and/or expect_len is non-zero, then the filter will return
1705       GE_REMCLOSE when it runs out of write data and  has  received  all  ex‐
1706       pected  data.   If  both are zero, the connection will not be closed by
1707       the gensio.
1708
1709   Options
1710       perf does not support readbuf.  It supports the following options:
1711
1712       writebuf=<n>
1713              Sets the size of the buffer to write to the child gensio.   Each
1714              write will be this size.  This defaults to zero.
1715
1716       write_len=<n>
1717              The number of bytes to write.
1718
1719       expect_len=<n>
1720              The number of bytes to expect from the other end.
1721

conacc

1723       accepter = conacc[(options)],<gensio string>
1724
1725       conacc  is  a gensio accepter that takes a gensio as a child.  When the
1726       accepter is started, it opens the child gensio.  When the child  gensio
1727       finishes  the  open,  it reports a new child for the accepter.  The re‐
1728       ported gensio can be used normally.
1729
1730       When the gensio is closed, when the close completes the  accepter  will
1731       attempt  to  re-open  the gensio immediately and will disable itself if
1732       the connect fails, unless retry-time is set.  This means  that  if  the
1733       gensio  has  some  sort  of random address (like a pty or a tcp address
1734       with the port set to zero) you can get a different address for the  re-
1735       opened  gensio.  So you must refetch the local address or local port in
1736       this case.
1737
1738   Options
1739       The readbuf option is not accepted.
1740
1741       retry-time=<gtime>
1742              Instead of restarting a closed connection immediately, this will
1743              cause  a  delay between the close and the re-open.  Also, if the
1744              connect fails, it will not disable itself, it will wait  another
1745              retry-time period and try the connect again.  See the section on
1746              gtime above.  The unit defaults to  milliseconds.   The  default
1747              value is zero.
1748
1749   Direct Allocation
1750       Allocated as a terminal gensio with gdata as a "const char *".  That is
1751       the specification of the gensio below it.
1752

mdns

1754       connecting = mdns[(options)][,<name>]
1755
1756       This gensio uses mDNS to find a service and then attempts to connect to
1757       it.  This can be convenient, it finds the connection type, address, and
1758       port for you, automatically adds telnet and rfc2217 if it's  available.
1759       The  mDNS name can be set as an option or as the string after the comma
1760       show above.
1761
1762       The name, type, host, and domain strings can be wildcarded  in  various
1763       ways.  See "STRING VALUES FOR WATCHES" in gensio_mdns(3) for details.
1764
1765   Options
1766       The  readbuf option is accepted, but if it is not specified the default
1767       value for readbuf will be taken for the sub-gensio is taken.  In  addi‐
1768       tion to readbuf, the mdns gensio takes the following options:
1769
1770       nostack[=true|false]
1771              By default the mdns gensio will attempt to use the "gensiostack"
1772              text string from the mDNS service.  If you don't want it  to  do
1773              this, setting this option will turn it off.
1774
1775       ignore-v6-link-local[=true|false]
1776              Ignore  IPv6  link  local addresses, ones starting with "fe80:".
1777              They cause problems on some systems.
1778
1779       mdnstimeout=<gtime>
1780              Set the amount of time to wait for mdns to find the  item.   See
1781              the  "gtime"  section for more info on how to set the time.  The
1782              default unit is milliseconds, default time is 1 second.  The de‐
1783              fault  setting  for mdnstimeout is not a gtime, it is in integer
1784              in  milliseconds.   You  may  also  use  "timeout"  instead   of
1785              "mdnstimeout", but not in the default.
1786
1787       name=<mdnsstr>
1788              Set  the  mdns  name  to  search for.  You generally want to set
1789              this, otherwise you will get the first thing that comes up  from
1790              the search.
1791
1792       type=<mdnsstr>
1793              Set the mdns type to search for.
1794
1795       domain=<mdnsstr>
1796              Set  the  mdns  domain  to  search for.  You generally don't use
1797              this.
1798
1799       host=<mdnsstr>
1800              Set the mdns host to search for.  You generally don't use this.
1801
1802       interface=<num>
1803              Set the network interface number to search on.  The  default  is
1804              -1, which means all interfaces.
1805
1806       nettype=unspec|ipv4|ipv6
1807              The  network  type to search for.  unspec means any type, other‐
1808              wise you can choose to limit it to ipv4 and ipv6.
1809
1810       nodelay[=true|false]
1811              Sets nodelay on the socket.  This will be ignored for udp.  Note
1812              that  the default value for mdns is ignored, if you don't set it
1813              here it will take the default value for the sub-gensio that gets
1814              chosen.  laddr=<addr> An address specification to bind to on the
1815              local socket to set the local address.
1816
1817   Direct Allocation
1818       Allocated as a terminal gensio with gdata as a "const char *".  That is
1819       the specification of the mdns as a string.
1820

kiss

1822       accepter = kiss[(options)]
1823       connecting = kiss[(options)]
1824
1825       A  gensio that implements the KISS amateur radio protocol for transfer‐
1826       ring data between a TNC and  AX25.   See  http://www.ax25.net/kiss.aspx
1827       for  details.  It contains a number of tunable parameters, you probably
1828       shouldn't mess with most of them.
1829
1830       This is a normal packet-oriented interface.
1831
1832       KISS supports multiple TNCs underneath it.  To write to a specific TNC,
1833       you  must  use the auxdata string "tnc:<n>" when writing.  If you don't
1834       set that, the TNC is assumed to be zero.  On  reading,  "tnc:<n>"  will
1835       always be in one of the auxdata fields.  You shouldn't set a TNC larger
1836       than the configured number of TNCs.
1837
1838       There is a 8-bit protocol field in the AX25 frame call the  PID.   This
1839       is  not  passed  in the data, it is also in the auxdata with the format
1840       "pid:<n>".  And to set the pid, pass it in the auxdata  on  write.   If
1841       you don't set the pid, it defaults to 240 (0xf0).
1842
1843
1844   Options
1845       kiss supports the following options:
1846
1847       readbuf=<n>
1848              Sets the maximum packet size that can be read from the TNC.  De‐
1849              faults to 256.
1850
1851       writebuf=<n>
1852              Sets the maximum packet size that can be  written  to  the  TNC.
1853              Defaults to 256.
1854
1855       tncs=<n>
1856              The number of supported TNCs.  Defaults to 1.
1857
1858       server[=yes|no]
1859              Is  this a KISS server or client.  A client will set the tunable
1860              parameters on the TNC.  A server is expected to be  a  TNC,  but
1861              this  isn't  fully  implemented yet as you can't get the tunable
1862              parameters.
1863
1864       setupstr=<string>
1865              Send the given string at startup to set up the device.
1866
1867       setup-delay=<n milliseconds>
1868              Wait for the given number  of  milliseconds  after  sending  the
1869              setup string before continuing operation.
1870
1871       d710[=yes|no]
1872              If  set  to  yes  or just "d710" is given, set the setupstr to a
1873              value for the Kenwood D710 radio.  This is the  same  as  doing:
1874              setupstr='xflow on\rhbaud 1200\rkiss on\rrestart\r'
1875
1876       d710-9600[=yes|no]
1877              If  set to yes or just "d710-9600" is given, set the setupstr to
1878              a value for the Kenwood D710 radio at 9600  bps.   This  is  the
1879              same    as    doing:    setupstr='xflow   on\rhbaud   9600\rkiss
1880              on\rrestart\r'
1881
1882       txdelay=<n>
1883              The KISS txdelay parameter,  in  milliseconds,  rounded  to  the
1884              nearest  power  of ten.  The maximum values is 2550.  Default is
1885              50ms.
1886
1887       persist=<n>
1888              The KISS "P" parameter, ranging from 0-255.  I don't  know  what
1889              this  means, the spec isn't clear.  You'll have to figure it out
1890              on your own.  Default is 63.
1891
1892       slottime=<n>
1893              The KISS slot time parameter, in milliseconds,  rounded  to  the
1894              nearest  power  of 10.  The maximum value is 2550ms, the default
1895              is 100ms.
1896
1897       fullduplex[=yes|no]
1898              Set's full duplex on the connection.
1899
1900       sethardware=<n>
1901              A hardware-specific control  value  ranging  from  0-255.   It's
1902              meaning depends on the hardware.  By default it is not set.
1903

ax25

1905       accepter = ax25[(options)]
1906       connecting = ax25[(options)]
1907
1908       A  gensio that implements the AX25 amateur radio protocol for transfer‐
1909       ring data.  You would generally run this on top of a KISS gensio.   See
1910       http://www.ax25.net for details.
1911
1912       This is a normal packet-oriented interface.
1913
1914       It  is  also a channel-based implementation.  Each AX25 connection to a
1915       remote system is implemented as a channel.  You can also have an uncon‐
1916       nected channel if you want to just receive UI frames.
1917
1918       There  is  no server/client setting on an ax25 gensio.  The protocol is
1919       symmetric, so it's not necessary.  An ax25 accepter will take the first
1920       connection  that  comes  in  and deliver it as a gensio, but after that
1921       there's really no difference.
1922
1923       When running as an accepter, incoming connections will be delivered  as
1924       new connections, not new channels.  This allows you to use an ax25 gen‐
1925       sio more naturally underneath a server without  having  to  know  about
1926       ax25  in  the  code.  For instance, to create a simple AX25 server that
1927       reflects all incoming data, you could create a reflector:
1928
1929              greflector -t kiss,tcp,1234
1930
1931       then you could create the server:
1932
1933              gensiot -i 'echo' --server -a \
1934                  'ax25(laddr=test-1),conacc,kiss,tcp,localhost,1234'
1935
1936       then you could connect to it:
1937
1938              gensiot  'ax25(laddr=test-2,addr="0,test-1,test-2"),kiss,tcp,lo‐
1939              calhost,1234'
1940
1941       So to use this, allocate an ax25 gensio.  If you want to make a connec‐
1942       tion, you must set the addr to a destination address.  By  default  the
1943       laddr  will  be set from the addr if the addr is supplied.  If you just
1944       want UI frames, you don't need to set an address (more on that  later).
1945       Then  you open the gensio.  An ax25 gensio without an address will just
1946       open immediately and start receiving UI packets as directed.   With  an
1947       addr  set,  it  will attempt to make a connection.  Once that is up (or
1948       fails), the open callback is called.
1949
1950   AX25 Addresses
1951       A gensio AX25 address string is in the form:
1952
1953              [ax25:]tncport,dest[:c|r],src[:c|r][,extra1[:h]
1954              [,extra2[:h][..]]]
1955
1956       tncport is a number from 0-15 specifying which TNC to  use.   dest  and
1957       src  and  subaddresses specifying the destination and source addresses.
1958       Note that the source address better match an laddr, or  the  connection
1959       won't  work.   extra  fields are also subaddresses.  These are used for
1960       routing (a function that is deprecated and no longer use) and  by  APRS
1961       for  it's own purposes, see the APRS spec for details.  The c, r, and h
1962       values are bits in the address that you generally don't care about, ex‐
1963       cept for the h field for APRS.
1964
1965       Subaddresses are in the form
1966
1967              callsign-n
1968
1969       where  callsign  is a set of alphanumeric digits (a-zA-Z0-9) and n is a
1970       number 0-15.  Lower case digits are converted to upper case in the  ad‐
1971       dress and not converted back on receipt.
1972
1973   Handling unconnected packets (UI frames)
1974       To  receive  UI  frames,  you must enable the GENSIO_CONTROL_ENABLE_OOB
1975       control on the gensio.  If you set the value to 1, you will receive  UI
1976       frames where the destination matches one of your laddrs.  If you set it
1977       to 2, you will receive all UI frames (promiscuous  mode).   0  disables
1978       receipt of UI frames.
1979
1980       UI  frames are reported with the "oob" in the auxdata, like out of band
1981       data.  Note that you must completely handle all the  UI  frame  in  the
1982       call.  If you don't consume all the data, it will not be called again.
1983
1984       You can have a channel that receives both connected data and UI frames,
1985       but you would generally have a separate channel with no  addr  set  for
1986       receiving  UI  frames.   If you don't set the laddr field, that channel
1987       can only be used for promiscuous mode.
1988
1989       On received packets, the auxdata will contain  a  field  starting  with
1990       "addr:"  and  the  rest is the gensio AX25 address in the packet.  When
1991       sending a UI frame, you must set "oob" and "addr:" fields in  the  aux‐
1992       data, with a valid address in the "addr:" field.
1993
1994   Options
1995       Option  values  for channels are all inherited from the options used to
1996       create the first channel, except for addr (which must be  supplied  for
1997       each  channel  if  you care) and laddr (which is only used on the first
1998       channel.  ax25 supports the following options:
1999
2000       readbuf=<n>
2001              Sets the maximum packet size that can be read.  Defaults to 256.
2002
2003       writebuf=<n>
2004              Sets the maximum packet size that can be written.   Defaults  to
2005              256.
2006
2007       readwindow=<n>
2008              Sets  the  maximum packet size that can be received and unacked.
2009              Defaults to 7 for extended and 4 for non-extended.
2010
2011       writewindow=<n>
2012              Sets the maximum number of packets that can be sent  unacked  to
2013              the  remote  side.  Defaults to 7 for extended and 4 for non-ex‐
2014              tended.
2015
2016       extended=<n>
2017              Set the extended mode.  Setting it to 1 will  enable  7-bit  se‐
2018              quence  numbers,  the connection will first attempt to use 7-bit
2019              sequence number.  If that fails, it will fall back to 3-bit  se‐
2020              quence numbers.
2021
2022              Setting the value to 2 will enable a non-standard operation that
2023              will add parameter negotiation to the connection startup.   Set‐
2024              ting  the readbuf, writebuf, readwindow, and writewindow without
2025              extended=2 really isn't very useful as without  the  negotiation
2026              it  will  be forced to fall back to the defaults.  If extended=2
2027              fails, it will fall back to extended=1.
2028
2029       laddr=<subaddr>[;<subaddr[...]]
2030              Set the addresses the ax25 gensio will receive packets for.  Ex‐
2031              cept  for  promiscuous UI mode, the destination of a packet must
2032              match one of these addresses to be handled.  This  can  only  be
2033              set  on  the  accepter or on the first connection and applies to
2034              all channels.
2035
2036              If you do not set this, but addr is set, the laddr will  be  set
2037              from the source address of addr.
2038
2039       addr=<ax25addr>
2040              Set  the  address  of the remote end of the connection.  Packets
2041              will be sent to this address.
2042
2043       crc[=yes|no]
2044              Enable CRC checking.  Default is off.
2045
2046       ign_emb_ua[=yes|no]
2047              Some AX.25 stacks do not properly reset themselves when they get
2048              a  second  SABM (due to a timeout) but they still send a UA.  If
2049              you are getting errors about receiving a UA while connected  and
2050              the connection hangs, try enabling this option.
2051
2052       srt=<n>
2053              The initial smoothed round trip time for the connection, in mil‐
2054              liseconds.  See the spec for details, you probably don't need to
2055              mess  with  it.  Note that this value you set here is multiplied
2056              by the number of digipeaters between the source and the destina‐
2057              tion for the actual value.  Defaults to 1500.
2058
2059       t2=<n> The  timer 2 value for the connection, in milliseconds.  See the
2060              spec for details, you probably don't need to mess with it.   De‐
2061              faults to 2 seconds.
2062
2063       t3=<n> The  timer 3 value for the connection, in milliseconds.  See the
2064              spec for details, you probably don't need to mess with it.   De‐
2065              faults to 300 seconds.
2066
2067       retries=<n>
2068              Number  of  retries  on a send before giving up and dropping the
2069              connection.  See the spec for details, you probably  don't  need
2070              to mess with it.  Defaults to 10.
2071

xlt

2073       accepter = xlt[(options)]
2074       connecting = xlt[(options)]
2075
2076       A gensio that translates characters.  This is primarily for translating
2077       line feeds and carraige returns, but may eventually be extended  to  do
2078       string substitutions and such.
2079
2080       The readbuf option is not available in this gensio.
2081
2082   Options
2083       in=<n>:<m>
2084              Translate  character n (a number, 0xnn for hex, 0nnn  for octal,
2085              or nn for decimal) to character m on data read from the gensio.
2086
2087       out=<n>:<m>
2088              Like in, but translate character n to character m on data  writ‐
2089              ten to the gensio.
2090
2091       nlcr   Translate  new  lines  to carraige returns on data read from the
2092              gensio, and carraige returns to new lines on data written to the
2093              gensio.
2094
2095       crnl   Translate  carraige  returns  to new lines on data read from the
2096              gensio, and new lines to carraige returns on data written to the
2097              gensio.
2098

keepopen

2100       connecting = keepopen[(options)]
2101
2102       A filter gensio that makes it appear to the user that the gensios below
2103       it are always open.  If the gensio below it goes away,  this  will  at‐
2104       tempt to re-open it periodically.
2105
2106       The readbuf option is not available in this gensio.
2107
2108   Options
2109       retry-time=<gtime>
2110              Set  the retry interval.  See the section on gtime for detail on
2111              this.  Defaults to milliseconds it no unit given.   The  default
2112              is 1 second.
2113
2114       discard-badwrites[=yes|no]
2115              Normally  this gensio will flow-control the upper layer when the
2116              lower gensio is not open.  If you  enable  this,  it  will  just
2117              throw write data away if the lower gensio is not open.
2118

script

2120       connecting = script[(options)] accepting = script[(options)]
2121
2122       A  filter  gensio  that allows an external program to interact with the
2123       child gensio before reporting that it is open.   The  external  program
2124       runs  with  its  stdio connected to the child of this gensio, so writes
2125       from the external program get written to the child and reads  from  the
2126       child  get written to the external program's stdin.  If the program re‐
2127       turns without error, the open for this gensio succeeds.  If the program
2128       returns an error, GE_LOCALCLOSED is reported as an open error.
2129
2130       The readbuf option is not available in this gensio.
2131
2132   Options
2133       script=<string>
2134              Run  the  program  given  in the string as the external program.
2135              This   is    equivalent    to    doing:    gensio=stdio(noredir-
2136              stderr),<string>, it just a shortcut.
2137
2138       gensio=<string>
2139              Instead  of  running  a program, run the given gensio.  When the
2140              gensio closes, handle an error.  If the gensio supported getting
2141              an error code, that is done.
2142

sound

2144       connecting = sound[(options)],<device>
2145
2146       The  sound  gensio  provides  access  to sound devices on the platform.
2147       It's an unusual gensio in many respects.  It's not terribly useful  for
2148       normal streaming operation.  It is a streaming operation, though, so it
2149       still fits.  But to avoid underruns and overruns, the stream has to  be
2150       continuously supplied or consumed.
2151
2152       The  stream  consists of bytes of binary data in the host's byte order.
2153       If the low-level sound interface uses a different  byte  order,  it  is
2154       converted  to the host's order in the gensio.  The gensio can also con‐
2155       vert data types.  If you ask for a  float  format  and  the  low  level
2156       driver  can  only  do  integers, the gensio will convert for you.  Each
2157       data item (byte, int16, etc) is called a sample.  So the driver  has  a
2158       user  format  (what  the  user  sees) and a PCM format (what the driver
2159       uses).
2160
2161       A stream has a number of channels, at least one.  Stereo, for instance,
2162       has  two  channels.   A  frame  consists  of  samples for all channels.
2163       Frames are always interleaved; the individual channels appear  as  suc‐
2164       cessive  data  items in the stream.  So in stereo, sample1 is channel 1
2165       in the first frame, sample2 is channel 2 in the first frame,  sample  3
2166       is channel 1 in the second frame, etc.
2167
2168       A  buffer is a set of frames.  A buffers's size is specified in frames,
2169       not bytes.  Reads are always provided in buffer size chunks.  If you do
2170       not  comsume all the data in a buffer, it will give you the rest of the
2171       buffer the next read, until the buffer  is  consumed.   Writes  can  be
2172       written  in any size, but it's generally most efficient to always write
2173       buffer sized chunks.
2174
2175       A number of buffers can also be specified.  You generally want a  large
2176       enough number that data can be smoothly written into the device without
2177       delay if the program lags a bit, but too large and you end up with  lag
2178       if you want to change the data being written..
2179
2180       A  sound gensio may have input, output, or both.  You specify which you
2181       want by setting the number of channels to a non-zero  value.   Most  of
2182       the  parameters  can be prefixed with "in" or "out" to specify that the
2183       parameter only applies to the input and output device.   If  you  don't
2184       have  that  prefix,  it  will apply to both the input and output.  Note
2185       that the input and output streams are completely independent; they  can
2186       have different type, format, rates, etc.
2187
2188       Different sound interfaces are available on platforms.  For Linux, alsa
2189       and file interfaces are available, and possibly portaudio, depending on
2190       how  it is compiled.  On Windows, win and file interfaces are available
2191       and possibly portaudio.  On Macos portaudio and file are available.
2192
2193       The device is specified on the command line.  The name is system-depen‐
2194       dent.   For  alsa, the name must match exactly.  You can use "aplay -L"
2195       or "arecord -L" to list input and output devices available.  Or you can
2196       use the "gsound -L" program.
2197
2198       For  Windows  and portaudio, the name just has to match part of the de‐
2199       vice's name.  Windows names always start with a number.   So,  for  in‐
2200       stance, if the output of "gsound -L" on your windows platform is:
2201
2202                  0:Microphone (Realtek(R) Audio)     input,inchans=2
2203                  0:Speakers (Realtek(R) Audio)       output,outchans=2
2204
2205       The  numbers  at the beginning are subject to change, so it's better to
2206       use part of the name like "Realtek", which will match  both  input  and
2207       output.   It  will not select an output-only device for input or an in‐
2208       put-only device for output.
2209
2210       On MacOS with portaudio you might see:
2211
2212                  0:USB Audio CODEC   output,outchans=2
2213                  1:USB Audio CODEC   input,inchans=2
2214                  2:Mac mini Speakers output,outchans=2 where  you  could  use
2215              "USB Audio" for the name.
2216
2217              For  file  type, the device name is a filename; data is streamed
2218              to/from the file in the PCM format.  If  the  filename  is  "-",
2219              then stdio is used instead of opening a file.
2220
2221              The readbuf option is not available in this gensio, obviously.
2222
2223   Options
2224       <samplerate>-<channels>-<format>
2225              For  simple  applications,  the sound gensio takes a compact and
2226              simple format as an option.  It specifies those things for  both
2227              the    input    and   output   channel.    So,   for   instance,
2228              "sound(44100-2-float)" would be CD-rate two channel using float‐
2229              ing point numbers.
2230
2231       list[=yes|no]
2232              Instead  of opening a sound device, the gensio will provide data
2233              about the various sound interfaces available.  Every  other  op‐
2234              tion but "type" is ignored.  If "type" is supplied, list the in‐
2235              terfaces for that type.  If "type" is not supplied, list the in‐
2236              terfaces for the default one.
2237
2238              The  data  will  be a string with each interfaces separated by a
2239              newline.  There will be an interface name, a tab, and the inter‐
2240              face specification.
2241
2242       outdev=<str>
2243              If the output device has a different name than the input device,
2244              it must be specified separately.
2245
2246       inbufsize=<n>, outbufsize=<n>, bufsize=<n>
2247              Specify the buffer size, in samples.  This defaults to 1024.
2248
2249       innbufs=<n>, outnbufs=<n>, nbufs=<n>
2250              Specify the number of buffers to use.  This may or  may  not  be
2251              used  depending  on  the interface type.  It's ignored for file,
2252              for instance.  Defaults to 100.
2253
2254       chans=<n>, inchans=<n>, outchans=<n>
2255              Set the number of input and output channels.  One of these  must
2256              be  specified,  if  you say chans it will set both the input and
2257              output number of channels.  If you only specify in or  out,  the
2258              other is not enabled.
2259
2260       inrate=<n>, outrate=<n>, rate=<n>
2261              The  sample  rate, in samples per second.  Common ones are 44100
2262              (CD), 48000 (DAT).
2263
2264       intype=<n>, outtype=<n>, type=<n>
2265              Set the interface type.  Must  be  "alsa"  (Linux  only),  "win"
2266              (Windows  only),  "portaudio"  (MacOS, generally) or "file".  If
2267              not set, this default to alsa on Linux, win on Windows, and por‐
2268              taudio no Macos.
2269
2270       informat=<n>, outformat=<n>, format=<n>
2271              Set  the  type  of  data to supply to the user.  This is one of:
2272              float64, float, s32, s32, s16, or s8.  User samples  are  always
2273              signed  and either floating point or integer.  Floating point is
2274              normalized from -1.0 to 1.0.  You must specify this.
2275
2276       inpformat=<n>, outpformat=<n>, pformat=<n>
2277              The data format on the PCM size.  You have all the data  formats
2278              specified  for  format  above.  The integer ones can be prefixed
2279              with "u" instead of "s" to make them unsigned  (like  u16),  and
2280              all may be suffixed with "le" or "be" to make them little or big
2281              endian (like float64_le).  If you do not specify this, the  gen‐
2282              sio  will  attempt  the same format as the user format.  If that
2283              doesn't work, it will attempt to pick the best  matching  format
2284              and convert.
2285

afskmdm

2287       connecting = afskmcm[(options)]
2288
2289       A  filter gensio that sits on top of the sound gensio and implements an
2290       Audio Frequency Shift Keying modem, like is used on AX.25  amateur  ra‐
2291       dio.  It must sit on top of a sound gensio.  Or, more accurately a gen‐
2292       sio  that   implements   the   GENSIO_CONTROL_IN_BUFSIZE,   GENSIO_CON‐
2293       TROL_OUT_BUFSIZE, GENSIO_CONTROL_IN_FORMAT, and GENSIO_CONTROL_OUT_FOR‐
2294       MAT controls.
2295
2296       Note that the sound gensio must supply a float user format.
2297
2298   Keying the Transmitter
2299       By default, afskmcm will not do anything specific to turn the transmit‐
2300       ter on and off. In this case the keying must be VOX, like a SignaLink.
2301
2302       If  you  need  some other way to key the transmitter, afskmcm provide a
2303       key option.  This create a gensio that is used to turn the  transmitter
2304       on and off.  Different types of keying options exist, specified by key‐
2305       type.
2306
2307       If keytype is rw, which is the default, then it will open the key  gen‐
2308       sio and send the keyon string and the keyoff string for this purpose.
2309
2310       If keytype is one of rts, rtsinv, dts, dtsinv then it will open the key
2311       gensio as a serial device and set the RTS/DTR lines appropriately.  The
2312       "inv"  options mean that setting the line "on" will turn off the trans‐
2313       mitter, setting it "off" will enable the transmitter.
2314
2315       You could do
2316
2317              keytype=rts,key="serialdev,/dev/serial/by-
2318              path/pci-0000:00:14.0-usb-0:4.4.2.4.2:1.0-port0"
2319
2320       to set up an RTS-base serial control on a port.
2321
2322       There  is a cm108 soundcard GPIO gensio available.  See that gensio for
2323       details, but you would generally do something like:
2324
2325              keytype=cm108
2326
2327       and this gensio will fetch the sound card identifier from the sound de‐
2328       vice  and use the cm108gpio gensio to key the device.  If you have some
2329       special setup where the default won't work, you can use
2330
2331              keytype=rw,key="cm108gpio,<dev>"
2332
2333       See the cm108gpio gensio docs for details.
2334
2335       If you need something more sophisicated, you could create your own pro‐
2336       gram to do the keying and add:
2337
2338              key="stdio,mykeyprog --parm1 --parm2",keyon="1",keyoff="0"
2339
2340       to  your  afskmdm  option  and  it would run the mykeyprog program when
2341       opened.  When it needed to transmit, it would write a "1"  (no  newline
2342       or  anything  sent) to the stdin of the program.  When the transmission
2343       was complete, it would write a "0".  Not numbers, these are "0" and "1"
2344       characters.
2345
2346       If you program sends output to stderr, you probably want to add stderr-
2347       to-stdout to the stdin so the stderr buffers doesn't fill up and  block
2348       the program.  Then stderr data will be ignored.
2349
2350       You  can  use rigctld with this.  I have the following rigctld setup on
2351       my system:
2352
2353              rigctld -m 1022 -r /dev/ttyUSB0 -s 4800 -P CM108 -p /dev/hidraw1
2354
2355       And I use the following in my configuration:
2356
2357              afskmdm(key="tcp,localhost,4532",keyon="T 1\n",keyoff="T 0\n")
2358
2359       You have to be careful of the quoting here, as  the  key  specification
2360       must  be in quotes because it will have commas.  Notice the use of "\n"
2361       in the strings for a new line.  Normal C "\" escape sequences are  han‐
2362       dled.   Also,  since the defaults for keyon and keyoff are what's given
2363       above, you don't have to specify those here.
2364
2365       Anything read in from the key gensio is ignored.
2366
2367   Options
2368       readbuf=<n>
2369              Sets the maximum packet size that can be read.  Defaults to 256.
2370
2371       writebuf=<n>
2372              Sets the maximum packet size that can be written.   Defaults  to
2373              256.
2374
2375       nchans=<n>, in_nchans=<n>, out_nchans=<n>
2376              Specify  how  many  channels  are coming from/going to the sound
2377              gensio.  The sound gensio interleaves  the  sound  for  multiple
2378              channels.  By default this is fetched from the sound gensio.
2379
2380       chan=<n>, in_chan=<n>, out_chan=<n>
2381              Which  specific channel to use.  One one channel is used for in‐
2382              put sound and output sound, the others  are  ignored  or  filled
2383              with zeros.  By default this is zero.
2384
2385       out_chans=<n>
2386              Specify  a  bitmask  of  which channels to output sound on.  The
2387              same sound will be output for all selected channel.  So n=1 will
2388              only  output  on channel 0, n=3 will output on channels 0 and 1,
2389              etc.  By default only channel 0 is output on.
2390
2391       samplerate=<n>, in_samplerate=<n>, out_samplerate=<n>
2392              The sample rate, samples per second, of the  data.   By  default
2393              this is fetched from the sound gensio.
2394
2395       checkax25[=true|false]
2396              Check that the packet is a valid AX.25 packet, that it has valid
2397              AX25 length and address.  Normally the AX.25  layer  does  this,
2398              but  this can be used when testing without an AX.25 layer to re‐
2399              ject bad packets.  Default to false.  Note that if you  set  crc
2400              to false, this option will not work.
2401
2402       crc[=true|false]
2403              Check  and  send CRCs on packets.  Normally you want the afskmdm
2404              code to do this, but can be  useful  for  testing.   Default  to
2405              true.
2406
2407       wmsgs=<n>
2408              The  number  of  working  messages at the same time.  If the bit
2409              fails the certainty test (see below), for every current  working
2410              message,  two  are created, one with each bit possibility, up to
2411              the count specified in this option.  These are kept until a mes‐
2412              sage  is  correctly received (with CRC) or the series of bits is
2413              not valid.
2414
2415              This way, if wmsg is 2^n, a message can be correctly decoded  if
2416              up  to  n  bits  are wrong.  So it's sort of an error correction
2417              code without a code.  Defaults to 32.
2418
2419       wmsg-extra=<n>
2420              Sets the number of extra amplification levels for the  mark  and
2421              space frequencies to try.  If set to 1, an extra complete detec‐
2422              tion is done with the space frequency amplified by 3db, then the
2423              mark  frequency  amplified by 3db.  If set to 2, it will do this
2424              with3db then 6db, and so on.  This can help compensate for  fil‐
2425              tering on the different frequencies.  Defaults to 1.
2426
2427       min-certainty=<float>
2428              A  floating  point  number  that specifies the minimum certainty
2429              above which a bit is considered good.  The ratio of  the  signal
2430              power  for  the  mark and space frequencies is calculated as the
2431              certainty.  If that certainty is below  min-certainty,  it  does
2432              the wmsgs procedure above.  Defaults to 2.0.
2433
2434       filttype=[fir|iir|none]
2435              A  2nd-order  low-pass  Butterworth IIR filter or a low-pass FIR
2436              filter is implemented on the input.  This selects which  filter,
2437              or no filter.  The IIR filter doesn't use very much CPU, the FIR
2438              filter uses a lot of CPU at higher sample rates.  This is mostly
2439              for  experimentation.  The default is IIR for sample rates above
2440              30000Hz and FIR for lower  sample  rates.   Lower  sample  rates
2441              don't  work  well with the IIR filter, but there's not much dif‐
2442              ference at higher sample rates.
2443
2444       lpcutoff=<n>
2445              This sets the cutoff frequency for the input filter.  Setting it
2446              to zero disables it.  The default is 2500Hz.
2447
2448       trfreq=<n>
2449              This  sets  the  transition  frequency width for the FIR filter.
2450              This is ignored for the  IIR  filter.   The  default  is  500Hz.
2451              Smaller numbers make a sharper cutoff but result in more CPU be‐
2452              ing used.
2453
2454       tx-preamble=<n>
2455              The time in milliseconds at the beginning of a message  that  is
2456              just  flags.   This  lets the receiver turn on and the other end
2457              synchronize.  Default is 300.
2458
2459       tx-tail=<n>
2460              The time in milliseconds at the end of the message that is  just
2461              flags.  Default is 100.
2462
2463       tx-predelay=<n>
2464              The  amount  of  time  to wait after another sender has finished
2465              sending a message before the transmit is  started.   Default  is
2466              500ms.
2467
2468       volume=<float>
2469              Sets  the  transmit volume, from 0.0-1.0.  Values above 1.0 will
2470              clip.  Default is .75.
2471
2472       key=<gensio string>
2473
2474       This creates a gensio that will be used to key the transmitter on and
2475              off.  See the discussion above on keying for more details.  key‐
2476              type=rw|rts|rtsinv|dtr|dtrinv|cm108 This sets the type of keying
2477              done,  per  the  discussion  above.   This  is  rw  by  default.
2478              keyon=<string>, keyoff=<string>
2479
2480       The strings to send to the key gensio to turn the transmitter on and
2481              off.   For  keytype=rw  only.  The default to "T 10 and "T 00 by
2482              default, which is what rigctld takes.  keybit=<n>
2483
2484       This sets the bit number to use on the cm108 keytype.  This is 3 by
2485              default.  full-duplex[=yes|no]
2486
2487       Treat the read and write streams as completely independent.  Transmit
2488              does not check if something is being  received  before  sending,
2489              all sends just start immediately.
2490

cm108gpio

2492       connecting = cm108gpio[(options)],<soundcard>
2493
2494       This  allows  a GPIO on a cm108 soundcard to be controlled.  Some radio
2495       sound card devices use one of these bits to key the  transmitter.   Any
2496       write with a '1' in it will enable the GPIO, any write with a '0' in it
2497       will disable the GPIO.  There are 8 available GPIOs, ranging 1-8,  most
2498       devices use 3.
2499
2500       For  Linux, <soundcard> is the soundcard number or device name given to
2501       open the sound device, generally  what's  right  after  the  ":",  like
2502       "plughw,1,0"  would  be  "1".  If it was "plughw,Device,0", it would be
2503       "Device".
2504
2505       For Windows, <soundcard> is the same thing you put for  the  soundcard,
2506       like "USB PnP Sound", or whatever "gsound -L" returns for your device.
2507
2508       The readbuf option is not available in this gensio.
2509
2510   Options
2511       bit=1-8
2512              The bit number to control.  The default is 3.
2513

Forking and gensios

2515       Unlike  normal  file  descriptors, when you fork with a gensio, you now
2516       have two unassociated copies of the gensios.  So if you  do  operations
2517       on  one,  it might mess up the other.  Even a close might cause issues,
2518       if you close an SSL connection, it sends data to the other end to close
2519       the connection, even if the other fork doesn't want that.
2520
2521       To avoid issues with this, you should generally first make sure that no
2522       thread is in a wait, service call, or any type of thing that would  ex‐
2523       amine  file descriptors or timers and act on them.  This is very impor‐
2524       tant, and you must do it before you fork.
2525
2526       Then after you fork, you should call:
2527
2528              gensio_disable(io)
2529
2530       on all the gensios that fork is  not  using,  then  free  the  gensios.
2531       Don't use close, use free.  Then you should call:
2532
2533              gensio_acc_disable(acc)
2534
2535       on  every gensio accepter that fork is not using, then free them.  If a
2536       connection is in progress and has not been reported  to  the  user,  it
2537       will be disabled then closed.
2538
2539       You cannot share a gensio between two different processes.  If a gensio
2540       is used in one fork, it must be disabled and closed in the other fork.
2541
2542       Another issue with forking on Linux is epoll.  An epoll fd is  not  du‐
2543       plicated on a fork, both forks get the same epoll fd.  If you close the
2544       epoll fd in one for, it will close it for the other.  To avoid this is‐
2545       sue, the os handler has a handle_fork() function that you must call af‐
2546       ter a fork in the new fork (not the  old  one).   It  will  handle  any
2547       cleanup  required  after  the  fork.   Other  systems may require other
2548       cleanups after a fork, so you should always call this after a fork.
2549

SEE ALSO

2551       gensiot(1), sctp(7), udp(7), tcp(7), unix(7)
2552

KNOWN PROBLEMS

2554       None.
2555

AUTHOR

2557       Corey Minyard <minyard@acm.org>
2558
2559
2560
2561Specifying a gensio                01/02/19                          gensio(5)
Impressum