nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 COMMENT(source: socat.yo)
2 mailto(socat@dest-unreach.org)
3  
4 def(unix)(0)(UN*X)
5 def(unixdomain)(0)(UNIX domain)
6 def(socat)(0)(bf(socat))
7 def(Socat)(0)(bf(Socat))
8 def(filan)(0)(bf(filan))
9 def(Filan)(0)(bf(Filan))
10 def(procan)(0)(bf(procan))
11 def(Procan)(0)(bf(Procan))
12  
13 manpage(socat)(1)()()()
14  
15 whenhtml(
16 label(CONTENTS)
17 manpagesection(CONTENTS)
18 link(NAME)(NAME)nl()
19 link(SYNOPSIS)(SYNOPSIS)nl()
20 link(DESCRIPTION)(DESCRIPTION)nl()
21 link(OPTIONS)(OPTIONS)nl()
22 link(ADDRESS SPECIFICATIONS)(ADDRESS_SPECIFICATIONS)nl()
23 link(ADDRESS TYPES)(ADDRESS_TYPES)nl()
24 link(ADDRESS OPTIONS)(ADDRESS_OPTIONS)nl()
25 link(DATA VALUES)(VALUES)nl()
26 link(EXAMPLES)(EXAMPLES)nl()
27 link(DIAGNOSTICS)(DIAGNOSTICS)nl()
28 link(FILES)(FILES)nl()
29 link(ENVIRONMENT VARIABLES)(ENVIRONMENT_VARIABLES)nl()
30 link(CREDITS)(CREDITS)nl()
31 link(VERSION)(VERSION)nl()
32 link(BUGS)(BUGS)nl()
33 link(SEE ALSO)(SEEALSO)nl()
34 )
35  
36 label(NAME)
37 manpagename(socat) (Multipurpose relay (SOcket CAT))
38  
39 label(SYNOPSIS)
40 manpagesynopsis()
41 tt(socat [options] <address-chain> <address-chain>)nl()
42 tt(socat -V)nl()
43 tt(socat -h[h[h]] | -?[?[?]])nl()
44 tt(filan)nl()
45 tt(procan)
46  
47 label(DESCRIPTION)
48 manpagedescription()
49  
50 Socat() is a command line based utility that establishes two bidirectional byte
51 streams and transfers data between them. Because the streams can be constructed
52 from a large set of different types of data sinks and sources
53 (see link(address types)(ADDRESS_TYPES)), and because lots of
54 link(address options)(ADDRESS_OPTIONS) may be applied to the streams, socat() can
55 be used for many different purposes.
56  
57 Filan() is a utility that prints information about its active file
58 descriptors to stdout. It has been written for debugging socat(), but might be
59 useful for other purposes too. Use the -h option to find more infos.
60  
61 Procan() is a utility that prints information about process parameters to
62 stdout. It has been written to better understand
63 some UNIX process properties and for debugging socat(), but might be
64 useful for other purposes too.
65  
66 The life cycle of a socat() instance typically consists of four phases.
67  
68 In the em(init) phase, the command line options are parsed and logging is
69 initialized.
70  
71 During the em(open) phase, socat() opens the first address chain and afterwards
72 the second address chain. These steps are usually blocking; thus, connection
73 requests or authentication dialogs must be completed before the next step is
74 started.
75  
76 In the em(transfer) phase, socat() watches both streams' read and write file
77 descriptors via code(select()), and, when data is available on one side em(and)
78 can be written to the other side, socat() reads it, performs newline
79 character conversions if required, and writes the data to the write file
80 descriptor of the other stream, then continues waiting for more data in both
81 directions.
82  
83 When one of the streams effectively reaches EOF, the em(closing) phase
84 begins. Socat() transfers the EOF condition to the other stream,
85 i.e. tries to shutdown only its write stream, giving it a chance to
86 terminate gracefully. For a defined time socat() continues to transfer data in
87 the other direction, but then closes all remaining channels and terminates.
88  
89  
90 label(OPTIONS)
91 manpageoptions()
92  
93 Socat() provides some command line options that modify the behaviour of the
94 program. They have nothing to do with so called
95 link(address options)(ADDRESS_OPTIONS) that are used as parts of link(address specifications)(ADDRESS_SPECIFICATIONS).
96  
97 startdit()
98 dit(bf(tt(-V)))
99 Print version and available feature information to stdout, and exit.
100 label(option_h)dit(bf(tt(-h | -?)))
101 Print a help text to stdout describing command line options and available address
102 types, and exit.
103 dit(bf(tt(-hh | -??)))
104 Like -h, plus a list of the short names of all available address options. Some options are
105 platform dependend, so this output is helpful for checking the particular
106 implementation.
107 dit(bf(tt(-hhh | -???)))
108 Like -hh, plus a list of all available address option names.
109 label(option_d)dit(bf(tt(-d)))
110 Without this option, only fatal and error messages are generated; applying
111 this option also prints warning messages. See link(DIAGNOSTICS)(DIAGNOSTICS)
112 for more information.
113 label(option_d_d)dit(bf(tt(-d -d))) Prints fatal, error, warning, and notice messages.
114 dit(bf(tt(-d -d -d))) Prints fatal, error, warning, notice, and info messages.
115 dit(bf(tt(-d -d -d -d))) Prints fatal, error, warning, notice, info, and debug
116 messages.
117 dit(bf(tt(-D)))
118 Logs information about file descriptors before starting the transfer phase.
119 dit(bf(tt(-ly[<facility>])))
120 Writes messages to syslog instead of stderr; severity as defined with -d
121 option. With optional link(<facility>)(TYPE_FACILITY), the syslog type can
122 be selected, default is "daemon". Third party libraries might not obey this
123 option.
124 dit(bf(tt(-lf))tt( <logfile>))
125 Writes messages to <logfile> [link(filename)(TYPE_FILENAME)] instead of
126 stderr. Some third party libraries, in particular libwrap, might not obey
127 this option.
128 dit(bf(tt(-ls)))
129 Writes messages to stderr (this is the default). Some third party libraries
130 might not obey this option, in particular libwrap appears to only log to
131 syslog.
132 label(option_lp)dit(bf(tt(-lp))tt(<progname>))
133 Overrides the program name printed in error messages and used for
134 constructing environment variable names.
135 dit(bf(tt(-lu)))
136 Extends the timestamp of error messages to microsecond resolution. Does not
137 work when logging to syslog.
138 label(option_lm)dit(bf(tt(-lm[<facility>])))
139 Mixed log mode. During startup messages are printed to stderr; when socat()
140 starts the transfer phase loop or daemon mode (i.e. after opening all
141 streams and before starting data transfer, or, with listening sockets with
142 fork option, before the first accept call), it switches logging to syslog.
143 With optional link(<facility>)(TYPE_FACILITY), the syslog type can be
144 selected, default is "daemon".
145 label(option_lh)dit(bf(tt(-lh)))
146 Adds hostname to log messages. Uses the value from environment variable
147 HOSTNAME or the value retrieved with tt(uname()) if HOSTNAME is not set.
148 dit(bf(tt(-v)))
149 Writes the transferred data not only to their target streams, but also to
150 stderr. The output format is text with some conversions for readability, and
151 prefixed with "> " or "< " indicating flow directions.
152 dit(bf(tt(-x)))
153 Writes the transferred data not only to their target streams, but also to
154 stderr. The output format is hexadecimal, prefixed with "> " or "< "
155 indicating flow directions. Can be combined with code(-v).
156 label(option_b)dit(bf(tt(-b))tt(<size>))
157 Sets the data transfer block <size> [link(size_t)(TYPE_SIZE_T)].
158 At most <size> bytes are transferred per step. Default is 8192 bytes.
159 label(option_s)dit(bf(tt(-s)))
160 By default, socat() terminates when an error occurred to prevent the process
161 from running when some option could not be applied. With this
162 option, socat() is sloppy with errors and tries to continue. Even with this
163 option, socat() will exit on fatals, and will abort connection attempts when
164 security checks failed.
165 label(option_t)dit(bf(tt(-t))tt(<timeout>))
166 When one channel has reached EOF, the write part of the other channel is shut
167 down. Then, socat() waits <timeout> [link(timeval)(TYPE_TIMEVAL)] seconds
168 before terminating. Default is 0.5 seconds. This timeout only applies to
169 addresses where write and read part can be closed independently. When during
170 the timeout interval the read part gives EOF, socat() terminates without
171 awaiting the timeout.
172 label(option_T)dit(bf(tt(-T))tt(<timeout>))
173 Total inactivity timeout: when socat() is already in the transfer loop and
174 nothing has happened for <timeout> [link(timeval)(TYPE_TIMEVAL)] seconds
175 (no data arrived, no interrupt occurred...) then it terminates.
176 Useful with protocols like UDP that cannot transfer EOF.
177 label(option_u)dit(bf(tt(-u)))
178 Uses unidirectional mode. The first address is only used for reading, and the
179 second address is only used for writing (link(example)(EXAMPLE_option_u)).
180 label(option_U)dit(bf(tt(-U)))
181 Uses unidirectional mode in reverse direction. The first address is only
182 used for writing, and the second address is only used for reading.
183 label(option_g)dit(bf(tt(-g)))
184 During address option parsing, don't check if the option is considered
185 useful in the given address environment. Use it if you want to force, e.g.,
186 appliance of a socket option to a serial device.
187 label(option_L)dit(bf(tt(-L))tt(<lockfile>))
188 If lockfile exists, exits with error. If lockfile does not exist, creates it
189 and continues, unlinks lockfile on exit.
190 label(option_W)dit(bf(tt(-W))tt(<lockfile>))
191 If lockfile exists, waits until it disappears. When lockfile does not exist,
192 creates it and continues, unlinks lockfile on exit.
193 label(option_4)dit(bf(tt(-4)))
194 Use IP version 4 in case that the addresses do not implicitly or explicitly
195 specify a version; this is the default.
196 label(option_6)dit(bf(tt(-6)))
197 Use IP version 6 in case that the addresses do not implicitly or explicitly
198 specify a version.
199 label(option_c)dit(bf(tt(-c<commtype>)))
200 Specifies the default communication type for inter address data
201 transfer. Takes a letter that means a communication type as explained
202 link(here)(TYPE_COMMTYPE):
203 startdit()
204 dit(bf(tt(s))) (lower case s) link(socketpair)(TYPE_COMMTYPE_SOCKETPAIR)
205 dit(bf(tt(S))) (upper case s) link(socketpairs)(TYPE_COMMTYPE_SOCKETPAIRS)
206 dit(bf(tt(P))) (upper case p) link(pipes)(TYPE_COMMTYPE_PIPES)
207 dit(bf(tt(t))) (lower case t) link(tcp)(TYPE_COMMTYPE_TCP)
208 dit(bf(tt(Y))) (upper case y) link(ptys)(TYPE_COMMTYPE_PTYS)
209 enddit()
210 enddit()
211  
212  
213 label(ADDRESS_SPECIFICATIONS)
214 manpagesection(ADDRESS SPECIFICATIONS)
215  
216 From the two em(address chain) command line argument, socat() gets instructions
217 and the necessary information for establishing the byte streams.
218  
219 An address chain consists of a sequence of zero or more em(inter addresses) and
220 one em(endpoint address), all separated by '|'.
221  
222 COMMENT(All addresses are either the first in a chain or have a left neighbor.)
223  
224 An endpoint address is always the last in an address chain; it has no right
225 neighbor. Endpoint addresses correlate to the addresses concept of socat()
226 version 1.
227  
228 Inter addresses always have a right neighbor (either another inter address or
229 an endpoint address). An inter address transfers data between its left neighbor
230 (or the main socat() transfer engine when it is the first in the chain) and its
231 right neighbor.
232  
233 Addresses (address specifications) usually consist of an address type
234 keyword, zero or more required address parameters separated by ':' from the
235 keyword and from each other, and zero or more address options separated by ','
236 from the address parameters and from each other.
237  
238 The keyword specifies the address type (e.g., TCP4-CONNECT, OPEN, EXEC). For
239 some keywords there exist alias names (TCP4 for TCP4-CONNECT or '-' for
240 STDIO). Keywords are case insensitive.
241 For a few special address types, the keyword may be omitted:
242 An address specification starting with a number is assumed to be an
243 link(FD)(ADDRESS_FD) (raw file descriptor) address;
244 if a '/' is found before the first ':' or ',', link(GOPEN)(ADDRESS_GOPEN)
245 (generic file open) is assumed.
246  
247 The required number and types of address parameters depend on the address
248 type. E.g., TCP4 requires a server specification (name or address), and a port
249 specification (number or service name).
250  
251 Some keywords are overloaded with multiple em(address forms) that may differ in
252 the following properties: Endpoint or inter address; number of
253 parameters; supported transfer directions on the left side. To see all
254 address forms available invoke socat with option link(-h)(option_h). The first
255 set of <tt>rwb</tt> flags describes the transfer directions on the address's
256 left side (read, write, and bidirectional, as seen by this address). The second
257 set describes the required direction on the right side; empty means it is an
258 endpoint address form.
259  
260 When parsing the addresses within an address chain socat() takes care of the
261 data transfer directions between consecutive addresses. For the first address
262 the directions are bidirectional per default, or unidirectional when when
263 link(option -u)(option_u) or link(-U)(option_U) is used. For the following
264 addresses, the required directions are derived from the right side directions
265 of the left neighbor.
266  
267 Zero or more address options may be given with each address. They influence the
268 address in some ways.
269 Options consist of an option keyword or an option keyword and a value
270 separated by '='. Option keywords are case insensitive.
271 For filtering the options that are useful with an address
272 type, each option is member of one option group. For
273 each address type there is a set of option groups allowed. Only options
274 belonging to one of these address groups may be used (except with link(option -g)(option_g)).
275  
276 label(ADDRESS_DUAL)
277 Address specifications following the above schema are also called em(single)
278 address specifications.
279 Two single addresses can be combined with "%" to form a em(dual) type
280 address. Here, the first address is used by socat() for transferring data from
281 left to right, and the second address from right to left. Of course this
282 requires bidirectional context, while both single addresses are integrated
283 unidirectionally.
284  
285 label(ADDRESS_REVERSE)
286 Inter addresses can be used in reverse mode by prefixing them with the
287 character '^' (caret). That means that the right side of the inter address is
288 connected to its left neighbor and its left side to its right neighbor.<br>
289 COMMENT(<em>Note: this can introduce ambiguities with the directions on the right side !!!tbd</em><br>)
290 Addresses within a dual type inter address can also be reverse.
291  
292 With socat() version 1.5.0 and higher, the lexical analysis tries to handle
293 quotes and parenthesis meaningfully and allows escaping of special characters.
294 If one of the characters ( { [ ' is found, the corresponding closing
295 character - ) } ] ' - is looked for; they may also be nested. Within these
296 constructs, socat()s special characters and strings ':' ',' '%' are not handled
297 specially. All those characters and strings can be escaped with \ or within "".
298  
299 label(ADDRESS_TYPES)
300 manpagesection(ADDRESS TYPES)
301  
302 This section describes the available address types with their keywords,
303 parameters, and semantics.
304  
305 startdit()
306 label(ADDRESS_CREAT)dit(bf(tt(CREATE:<filename>)))
307 Opens link(<filename>)(TYPE_FILENAME) with code(creat()) and uses the file
308 descriptor for writing.
309 This address type requires write-only context, because a file opened with
310 code(creat) cannot be read from. nl()
311 Flags like O_LARGEFILE cannot be applied. If you need them use
312 link(OPEN)(ADDRESS_OPEN) with options
313 link(create)(OPTION_O_CREAT),link(create)(OPTION_O_TRUNC). nl()
314 <filename> must be a valid existing or not existing path.
315 If <filename> is a named pipe, code(creat()) might block;
316 if <filename> refers to a socket, this is an error.nl()
317 Option groups: link(FD)(GROUP_FD),link(REG)(GROUP_REG),link(NAMED)(GROUP_NAMED) nl()
318 Useful options:
319 link(mode)(OPTION_MODE),
320 link(user)(OPTION_USER),
321 link(group)(OPTION_GROUP),
322 link(unlink-early)(OPTION_UNLINK_EARLY),
323 link(unlink-late)(OPTION_UNLINK_LATE),
324 link(append)(OPTION_APPEND)nl()
325 See also: link(OPEN)(ADDRESS_OPEN), link(GOPEN)(ADDRESS_GOPEN)
326 label(ADDRESS_EXEC)dit(bf(tt(EXEC:<command-line>)))
327 Is an alias for link(EXEC2)(ADDRESS_EXEC2)
328 label(ADDRESS_EXEC1)dit(bf(tt(EXEC1:<command-line>)))
329 This is a variation of the link(EXEC2)(ADDRESS_EXEC2) address that provides
330 unidirectional communication within an address chain: socat() connects the
331 program's stdin to its left neighbor and its stdout to its right neighbor.
332 label(ADDRESS_EXEC2)dit(bf(tt(EXEC2:<command-line>)))
333 Forks a sub process that establishes communication with its parent process
334 and invokes the specified program with code(execvp()).
335 link(<command-line>)(TYPE_COMMAND_LINE) is a simple command
336 with arguments separated by spaces. If the program name
337 contains '/', only the part after the last '/' is taken as ARGV[0]. If the
338 program name is a relative
339 path, the code(execvp()) semantics for finding the program via
340 code($PATH) apply. nl()
341 This address may be used as an endpoint address where socat() writes data to
342 stdin of the process and reads from its stdout using two unixdomain()
343 sockets generated by code(socketpair()) per default
344 (link(example)(EXAMPLE_ADDRESS_EXEC)), or as an inter address where
345 socat() connects the program's stdio to its left neighbor and its file
346 descriptors 3 and 4 to its right neighbor. nl()
347 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(EXEC)(GROUP_EXEC),link(FORK)(GROUP_FORK),link(TERMIOS)(GROUP_TERMIOS) nl()
348 Useful options:
349 link(path)(OPTION_PATH),
350 link(fdin)(OPTION_FDIN),
351 link(fdout)(OPTION_FDOUT),
352 link(chroot)(OPTION_CHROOT),
353 link(su)(OPTION_SUBSTUSER),
354 link(su-d)(OPTION_SUBSTUSER_DELAYED),
355 link(nofork)(OPTION_NOFORK),
356 link(commtype)(OPTION_COMMTYPE),
357 link(stderr)(OPTION_STDERR),
358 link(ctty)(OPTION_CTTY),
359 link(setsid)(OPTION_SETSID),
360 link(login)(OPTION_LOGIN),
361 link(sigint)(OPTION_SIGINT),
362 link(sigquit)(OPTION_SIGQUIT)nl()
363 See also: link(SYSTEM)(ADDRESS_SYSTEM)
364 label(ADDRESS_FD)dit(bf(tt(FD:<fdnum>)))
365 Uses the file descriptor link(<fdnum>)(TYPE_FDNUM). It must already exist as
366 valid unix() file descriptor.nl()
367 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl()
368 See also:
369 link(STDIO)(ADDRESS_STDIO),
370 link(STDIN)(ADDRESS_STDIN),
371 link(STDOUT)(ADDRESS_STDOUT),
372 link(STDERR)(ADDRESS_STDERR)
373 label(ADDRESS_GOPEN)dit(bf(tt(GOPEN:<filename>)))
374 (Generic open) This address type tries to handle any file system entry
375 except directories usefully. link(<filename>)(TYPE_FILENAME) may be a
376 relative or absolute path. If it already exists, its type is checked.
377 In case of a unixdomain() socket, socat() connects; if connecting fails,
378 socat() assumes a datagram socket and uses code(sendto()) calls.
379 If the entry is not a socket, socat() opens it applying the code(O_APPEND)
380 flag.
381 If it does not exist, it is opened with flag
382 code(O_CREAT) as a regular file (link(example)(EXAMPLE_ADDRESS_GOPEN)).nl()
383 Option groups: link(FD)(GROUP_FD),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN) nl()
384 See also:
385 link(OPEN)(ADDRESS_OPEN),
386 link(CREATE)(ADDRESS_CREAT),
387 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT)
388  
389 label(ADDRESS_IP_SENDTO)dit(bf(tt(IP-SENDTO:<host>:<protocol>)))
390 Opens a raw IP socket. Depending on host specification or option link(pf)(OPTION_PROTOCOL_FAMILY), IP protocol version
391 4 or 6 is used. It uses link(<protocol>)(TYPE_PROTOCOL) to send packets
392 to <host> [link(IP address)(TYPE_IP_ADDRESS)] and receives packets from
393 host, ignores packets from other hosts.
394 Protocol 255 uses the raw socket with the IP header being part of the
395 data.nl()
396 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl()
397 Useful options:
398 link(pf)(OPTION_PROTOCOL_FAMILY),
399 link(ttl)(OPTION_TTL) nl()
400 See also:
401 link(IP4-SENDTO)(ADDRESS_IP4_SENDTO),
402 link(IP6-SENDTO)(ADDRESS_IP6_SENDTO),
403 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM),
404 link(IP-RECV)(ADDRESS_IP_RECV),
405 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO),
406 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO)
407 label(ADDRESS_INTERFACE)dit(bf(tt(INTERFACE:<interface>)))
408 Communicates with a network connected on an interface using raw packets
409 including link level data. link(<interface>)(TYPE_INTERFACE) is the name of
410 the network interface. Currently only available on Linux.
411 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET) nl()
412 Useful options:
413 link(pf)(OPTION_PROTOCOL_FAMILY),
414 link(type)(OPTION_SO_TYPE)nl()
415 See also: link(ip-recv)(ADDRESS_IP_RECV)
416 label(ADDRESS_IP4_SENDTO)dit(bf(tt(IP4-SENDTO:<host>:<protocol>)))
417 Like link(IP-SENDTO)(ADDRESS_IP_SENDTO), but always uses IPv4.nl()
418 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4) nl()
419 label(ADDRESS_IP6_SENDTO)dit(bf(tt(IP6-SENDTO:<host>:<protocol>)))
420 Like link(IP-SENDTO)(ADDRESS_IP_SENDTO), but always uses IPv6.nl()
421 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6) nl()
422  
423 label(ADDRESS_IP_DATAGRAM)dit(bf(tt(IP-DATAGRAM:<address>:<protocol>)))
424 Sends outgoing data to the specified address which may in particular be a
425 broadcast or multicast address. Packets arriving on the local socket are
426 checked if their source addresses match
427 link(RANGE)(OPTION_RANGE) or link(TCPWRAP)(OPTION_TCPWRAPPERS)
428 options. This address type can for example be used for implementing
429 symmetric or asymmetric broadcast or multicast communications.nl()
430 Option groups: link(FD)(GROUP_FD), link(SOCKET)(GROUP_SOCKET),
431 link(IP4)(GROUP_IP4), link(IP6)(GROUP_IP6), link(RANGE)(GROUP_RANGE) nl()
432 Useful options:
433 link(bind)(OPTION_BIND),
434 link(range)(OPTION_RANGE),
435 link(tcpwrap)(OPTION_TCPWRAPPERS),
436 link(broadcast)(OPTION_SO_BROADCAST),
437 link(ip-multicast-loop)(OPTION_IP_MULTICAST_LOOP),
438 link(ip-multicast-ttl)(OPTION_IP_MULTICAST_TTL),
439 link(ip-multicast-if)(OPTION_IP_MULTICAST_IF),
440 link(ip-add-membership)(OPTION_IP_ADD_MEMBERSHIP),
441 link(ttl)(OPTION_TTL),
442 link(tos)(OPTION_TOS),
443 link(pf)(OPTION_PROTOCOL_FAMILY)nl()
444 See also:
445 link(IP4-DATAGRAM)(ADDRESS_IP4_DATAGRAM),
446 link(IP6-DATAGRAM)(ADDRESS_IP6_DATAGRAM),
447 link(IP-SENDTO)(ADDRESS_IP_SENDTO),
448 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM),
449 link(IP-RECV)(ADDRESS_IP_RECV),
450 link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM)
451 label(ADDRESS_IP4_DATAGRAM)dit(bf(tt(IP4-DATAGRAM:<host>:<protocol>)))
452 Like link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM), but always uses IPv4.
453 (link(example)(EXAMPLE_ADDRESS_IP4_BROADCAST_CLIENT))nl()
454 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(RANGE)(GROUP_RANGE) nl()
455 label(ADDRESS_IP6_DATAGRAM)dit(bf(tt(IP6-DATAGRAM:<host>:<protocol>)))
456 Like link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM), but always uses IPv6. Please
457 note that IPv6 does not know broadcasts.nl()
458 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl()
459  
460 label(ADDRESS_IP_RECVFROM)dit(bf(tt(IP-RECVFROM:<protocol>)))
461 Opens a raw IP socket of link(<protocol>)(TYPE_PROTOCOL). Depending on option link(pf)(OPTION_PROTOCOL_FAMILY), IP protocol version
462 4 or 6 is used. It receives one packet from an unspecified peer and may send one or more answer packets to that peer.
463 This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process.
464 This allows a behaviour similar to typical UDP based servers like ntpd or
465 named.nl()
466 Please note that the reply packets might be fetched as incoming traffic when
467 sender and receiver IP address are identical because there is no port number
468 to distinguish the sockets.nl()
469 This address works well with IP-SENDTO address peers (see above).
470 Protocol 255 uses the raw socket with the IP header being part of the
471 data.nl()
472 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl()
473 Useful options:
474 link(pf)(OPTION_PROTOCOL_FAMILY),
475 link(fork)(OPTION_FORK),
476 link(range)(OPTION_RANGE),
477 link(ttl)(OPTION_TTL),
478 link(broadcast)(OPTION_SO_BROADCAST)nl()
479 See also:
480 link(IP4-RECVFROM)(ADDRESS_IP4_RECVFROM),
481 link(IP6-RECVFROM)(ADDRESS_IP6_RECVFROM),
482 link(IP-SENDTO)(ADDRESS_IP_SENDTO),
483 link(IP-RECV)(ADDRESS_IP_RECV),
484 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM),
485 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM)
486 label(ADDRESS_IP4_RECVFROM)dit(bf(tt(IP4-RECVFROM:<protocol>)))
487 Like link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), but always uses IPv4.nl()
488 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl()
489 label(ADDRESS_IP6_RECVFROM)dit(bf(tt(IP6-RECVFROM:<protocol>)))
490 Like link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), but always uses IPv6.nl()
491 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl()
492  
493 label(ADDRESS_IP_RECV)dit(bf(tt(IP-RECV:<protocol>)))
494 Opens a raw IP socket of link(<protocol>)(TYPE_PROTOCOL). Depending on option link(pf)(OPTION_PROTOCOL_FAMILY), IP protocol version
495 4 or 6 is used. It receives packets from multiple unspecified peers and merges the data.
496 No replies are possible.
497 It can be, e.g., addressed by socat() IP-SENDTO address peers.
498 Protocol 255 uses the raw socket with the IP header being part of the
499 data.nl()
500 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl()
501 Useful options:
502 link(pf)(OPTION_PROTOCOL_FAMILY),
503 link(range)(OPTION_RANGE)nl()
504 See also:
505 link(IP4-RECV)(ADDRESS_IP4_RECV),
506 link(IP6-RECV)(ADDRESS_IP6_RECV),
507 link(IP-SENDTO)(ADDRESS_IP_SENDTO),
508 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM),
509 link(UDP-RECV)(ADDRESS_UDP_RECV),
510 link(UNIX-RECV)(ADDRESS_UNIX_RECV)
511 label(ADDRESS_IP4_RECV)dit(bf(tt(IP4-RECV:<protocol>)))
512 Like link(IP-RECV)(ADDRESS_IP_RECV), but always uses IPv4.nl()
513 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(RANGE)(GROUP_RANGE) nl()
514 label(ADDRESS_IP6_RECV)dit(bf(tt(IP6-RECV:<protocol>)))
515 Like link(IP-RECV)(ADDRESS_IP_RECV), but always uses IPv6.nl()
516 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl()
517  
518 label(ADDRESS_OPEN)dit(bf(tt(OPEN:<filename>)))
519 Opens link(<filename>)(TYPE_FILENAME) using the code(open()) system call
520 (link(example)(EXAMPLE_ADDRESS_OPEN)).
521 This operation fails on unixdomain() sockets. nl()
522 Note: This address type is rarly useful in bidirectional mode.nl()
523 Option groups: link(FD)(GROUP_FD),link(REG)(GROUP_REG),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN) nl()
524 Useful options:
525 link(creat)(OPTION_O_CREAT),
526 link(excl)(OPTION_EXCL),
527 link(noatime)(OPTION_O_NOATIME),
528 link(nofollow)(OPTION_NOFOLLOW),
529 link(append)(OPTION_APPEND),
530 link(rdonly)(OPTION_RDONLY),
531 link(wronly)(OPTION_WRONLY),
532 link(lock)(OPTION_LOCK),
533 link(readbytes)(OPTION_READBYTES),
534 link(ignoreeof)(OPTION_IGNOREEOF)nl()
535 See also:
536 link(CREATE)(ADDRESS_CREAT),
537 link(GOPEN)(ADDRESS_GOPEN),
538 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT)
539 label(ADDRESS_OPENSSL_CONNECT)dit(bf(tt(OPENSSL:<host>:<port>)))
540 Tries to establish a SSL connection to <port> [link(TCP
541 service)(TYPE_TCP_SERVICE)] on
542 <host> [link(IP address)(TYPE_IP_ADDRESS)] using TCP/IP version 4 or 6
543 depending on address specification, name resolution, or option
544 link(pf)(OPTION_PROTOCOL_FAMILY).nl()
545 NOTE: Up to version 1.7.2.4 and 2.0.0-b7
546 the server certificate was only checked for validity against the system
547 certificate store or link(cafile)(OPTION_OPENSSL_CAFILE) or
548 link(capath)(OPTION_OPENSSL_CAPATH),
549 but not for match with the server's name or its IP address.
550 Since version 1.7.3.0 and 2.0.0-b8 socat checks the peer certificate for match with the
551 <host> parameter or the value of the
552 link(openssl-commonname)(OPTION_OPENSSL_COMMONNAME) option.
553 Socat tries to match it against the certificates subject commonName,
554 and the certifications extension subjectAltName DNS names. Wildcards in the
555 certificate are supported.nl()
556 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(OPENSSL)(GROUP_OPENSSL),link(RETRY)(GROUP_RETRY) nl()
557 Useful options:
558 link(cipher)(OPTION_OPENSSL_CIPHERLIST),
559 link(method)(OPTION_OPENSSL_METHOD),
560 link(verify)(OPTION_OPENSSL_VERIFY),
561 link(commonname)(OPTION_OPENSSL_COMMONNAME)
562 link(cafile)(OPTION_OPENSSL_CAFILE),
563 link(capath)(OPTION_OPENSSL_CAPATH),
564 link(certificate)(OPTION_OPENSSL_CERTIFICATE),
565 link(key)(OPTION_OPENSSL_KEY),
566 link(bind)(OPTION_BIND),
567 link(pf)(OPTION_PROTOCOL_FAMILY),
568 link(connect-timeout)(OPTION_CONNECT_TIMEOUT),
569 link(sourceport)(OPTION_SOURCEPORT),
570 link(retry)(OPTION_RETRY)nl()
571 See also:
572 link(OPENSSL-LISTEN)(ADDRESS_OPENSSL_LISTEN),
573 link(TCP)(ADDRESS_TCP_CONNECT)
574 label(ADDRESS_OPENSSL_LISTEN)dit(bf(tt(OPENSSL-LISTEN:<port>)))
575 Listens on tcp <port> [link(TCP service)(TYPE_TCP_SERVICE)].
576 The IP version is 4 or the one specified with
577 link(pf)(OPTION_PROTOCOL_FAMILY). When a
578 connection is accepted, this address behaves as SSL server.nl()
579 Note: You probably want to use the link(certificate)(OPTION_OPENSSL_CERTIFICATE) option with this address.nl()
580 NOTE: The client certificate is only checked for validity against
581 link(cafile)(OPTION_OPENSSL_CAFILE) or link(capath)(OPTION_OPENSSL_CAPATH),
582 but not for match with the client's name or its IP address!nl()
583 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(LISTEN)(GROUP_LISTEN),link(OPENSSL)(GROUP_OPENSSL),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(RETRY)(GROUP_RETRY) nl()
584 Useful options:
585 link(pf)(OPTION_PROTOCOL_FAMILY),
586 link(cipher)(OPTION_OPENSSL_CIPHERLIST),
587 link(method)(OPTION_OPENSSL_METHOD),
588 link(verify)(OPTION_OPENSSL_VERIFY),
589 link(commonname)(OPTION_OPENSSL_COMMONNAME)
590 link(cafile)(OPTION_OPENSSL_CAFILE),
591 link(capath)(OPTION_OPENSSL_CAPATH),
592 link(certificate)(OPTION_OPENSSL_CERTIFICATE),
593 link(key)(OPTION_OPENSSL_KEY),
594 link(fork)(OPTION_FORK),
595 link(bind)(OPTION_BIND),
596 link(range)(OPTION_RANGE),
597 link(tcpwrap)(OPTION_TCPWRAPPERS),
598 link(su)(OPTION_SUBSTUSER),
599 link(reuseaddr)(OPTION_REUSEADDR),
600 link(retry)(OPTION_RETRY)nl()
601 See also:
602 link(OPENSSL)(ADDRESS_OPENSSL_CONNECT),
603 link(TCP)(ADDRESS_TCP_CONNECT)
604 label(ADDRESS_NAMED_PIPE)dit(bf(tt(PIPE:<filename>)))
605 If link(<filename>)(TYPE_FILENAME) already exists, it is opened.
606 If it does not exist, a named pipe is created and opened. Beginning with
607 socat() version 1.4.3, the named pipe is removed when the address is closed
608 (but see option link(unlink-close)(OPTION_UNLINK_CLOSE)nl()
609 Note: When a pipe is used for both reading and writing, it works
610 as echo service.nl()
611 Note: When a pipe is used for both reading and writing, and socat() tries
612 to write more bytes than the pipe can buffer (Linux 2.4: 2048 bytes), socat
613 might block. Consider using socat() option, e.g., link(code(-b
614 2048))(option_b) nl()
615 Option groups: link(FD)(GROUP_FD),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN) nl()
616 Useful options:
617 link(rdonly)(OPTION_RDONLY),
618 link(nonblock)(OPTION_NONBLOCK),
619 link(group)(OPTION_GROUP),
620 link(user)(OPTION_USER),
621 link(mode)(OPTION_MODE),
622 link(unlink-early)(OPTION_UNLINK_EARLY)nl()
623 See also: link(unnamed pipe)(ADDRESS_UNNAMED_PIPE)
624 label(ADDRESS_UNNAMED_PIPE)dit(bf(tt(PIPE)))
625 Creates an unnamed pipe and uses it for reading and writing. It works as an
626 echo, because everything written
627 to it appeares immediately as read data.nl()
628 Note: When socat() tries to write more bytes than the pipe can queue (Linux
629 2.4: 2048 bytes), socat() might block. Consider, e.g., using
630 option link(code(-b 2048))(option_b) nl()
631 Option groups: link(FD)(GROUP_FD) nl()
632 See also: link(named pipe)(ADDRESS_NAMED_PIPE)
633 label(ADDRESS_PROXY_CONNECT)dit(bf(tt(PROXY:<proxy>:<hostname>:<port>)))
634 Connects to an HTTP proxy server on port 8080 using TCP/IP version 4 or 6
635 depending on address specification, name resolution, or option
636 link(pf)(OPTION_PROTOCOL_FAMILY), and sends a CONNECT
637 request for hostname:port. If the proxy grants access and succeeds to
638 connect to the target, data transfer between socat() and the target can
639 start. Note that the traffic need not be HTTP but can be an arbitrary
640 protocol. nl()
641 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(HTTP)(GROUP_HTTP),link(RETRY)(GROUP_RETRY) nl()
642 Useful options:
643 link(proxyport)(OPTION_PROXYPORT),
644 link(ignorecr)(OPTION_IGNORECR),
645 link(proxyauth)(OPTION_PROXY_AUTHORIZATION),
646 link(resolve)(OPTION_PROXY_RESOLVE),
647 link(crnl)(OPTION_CRNL),
648 link(bind)(OPTION_BIND),
649 link(connect-timeout)(OPTION_CONNECT_TIMEOUT),
650 link(mss)(OPTION_MSS),
651 link(sourceport)(OPTION_SOURCEPORT),
652 link(retry)(OPTION_RETRY) nl()
653 See also: link(SOCKS)(ADDRESS_SOCKS4), link(TCP)(ADDRESS_TCP_CONNECT)
654 label(ADDRESS_PTY)dit(bf(tt(PTY)))
655 Generates a pseudo terminal (pty) and uses its master side. Another process
656 may open the pty's slave side using it like a serial line or terminal.
657 (link(example)(EXAMPLE_ADDRESS_PTY)). If
658 both the ptmx and the openpty mechanisms are available, ptmx is used
659 (POSIX).nl()
660 Option groups: link(FD)(GROUP_FD),link(NAMED)(GROUP_NAMED),link(PTY)(GROUP_PTY),link(TERMIOS)(GROUP_TERMIOS) nl()
661 Useful options:
662 link(link)(OPTION_SYMBOLIC_LINK),
663 link(openpty)(OPTION_OPENPTY),
664 link(wait-slave)(OPTION_PTY_WAIT_SLAVE),
665 link(mode)(OPTION_MODE),
666 link(user)(OPTION_USER),
667 link(group)(OPTION_GROUP)nl()
668 See also:
669 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN),
670 link(PIPE)(ADDRESS_NAMED_PIPE),
671 link(EXEC)(ADDRESS_EXEC), link(SYSTEM)(ADDRESS_SYSTEM)
672 label(ADDRESS_READLINE)dit(bf(tt(READLINE)))
673 Uses GNU readline and history on stdio to allow editing and reusing input
674 lines (link(example)(EXAMPLE_ADDRESS_READLINE)). This requires the GNU readline and
675 history libraries. Note that stdio should be a (pseudo) terminal device,
676 otherwise readline does not seem to work.nl()
677 Option groups: link(FD)(GROUP_FD),link(READLINE)(GROUP_READLINE),link(TERMIOS)(GROUP_TERMIOS) nl()
678 Useful options:
679 link(history)(OPTION_HISTORY),
680 link(noecho)(OPTION_NOECHO)nl()
681 See also:
682 link(STDIO)(ADDRESS_STDIO)
683 label(ADDRESS_SCTP_CONNECT)dit(bf(tt(SCTP-CONNECT:<host>:<port>)))
684 Establishes an SCTP stream connection to the specified <host> [link(IP
685 address)(TYPE_IP_ADDRESS)] and <port> [link(TCP service)(TYPE_TCP_SERVICE)]
686 using TCP/IP version 4 or 6 depending on address specification, name
687 resolution, or option link(pf)(OPTION_PROTOCOL_FAMILY) (link(example)(EXAMPLE_SCTP_OPENSSL_IP6)).nl()
688 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl()
689 Useful options:
690 link(bind)(OPTION_BIND),
691 link(pf)(OPTION_PROTOCOL_FAMILY),
692 link(connect-timeout)(OPTION_CONNECT_TIMEOUT),
693 link(tos)(OPTION_TOS),
694 link(mtudiscover)(OPTION_MTUDISCOVER),
695 link(sctp-maxseg)(OPTION_SCTP_MAXSEG),
696 link(sctp-nodelay)(OPTION_SCTP_NODELAY),
697 link(nonblock)(OPTION_NONBLOCK),
698 link(sourceport)(OPTION_SOURCEPORT),
699 link(retry)(OPTION_RETRY),
700 link(readbytes)(OPTION_READBYTES)nl()
701 See also:
702 link(SCTP4-CONNECT)(ADDRESS_SCTP4_CONNECT),
703 link(SCTP6-CONNECT)(ADDRESS_SCTP6_CONNECT),
704 link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN),
705 link(TCP-CONNECT)(ADDRESS_TCP_CONNECT)
706 label(ADDRESS_SCTP4_CONNECT)dit(bf(tt(SCTP4-CONNECT:<host>:<port>)))
707 Like link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT), but only supports IPv4 protocol.nl()
708 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(SCTP)(GROUP_SCTP),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl()
709 label(ADDRESS_SCTP6_CONNECT)dit(bf(tt(SCTP6-CONNECT:<host>:<port>)))
710 Like link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT), but only supports IPv6 protocol.nl()
711 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl()
712 label(ADDRESS_SCTP_LISTEN)dit(bf(tt(SCTP-LISTEN:<port>)))
713 Listens on <port> [link(TCP service)(TYPE_TCP_SERVICE)] and accepts a
714 TCP/IP connection. The IP version is 4 or the one specified with
715 address option link(pf)(OPTION_PROTOCOL_FAMILY), socat() option
716 (link(-4)(option_4), link(-6)(option_6)), or environment variable link(SOCAT_DEFAULT_LISTEN_IP)(ENV_SOCAT_DEFAULT_LISTEN_IP).
717 Note that opening
718 this address usually blocks until a client connects.nl()
719 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(RETRY)(GROUP_RETRY) nl()
720 Useful options:
721 link(crnl)(OPTION_CRNL),
722 link(fork)(OPTION_FORK),
723 link(bind)(OPTION_BIND),
724 link(range)(OPTION_RANGE),
725 link(tcpwrap)(OPTION_TCPWRAPPERS),
726 link(pf)(OPTION_PROTOCOL_FAMILY),
727 link(max-children)(OPTION_MAX_CHILDREN),
728 link(backlog)(OPTION_BACKLOG),
729 link(sctp-maxseg)(OPTION_SCTP_MAXSEG),
730 link(sctp-nodelay)(OPTION_SCTP_NODELAY),
731 link(su)(OPTION_SUBSTUSER),
732 link(reuseaddr)(OPTION_REUSEADDR),
733 link(retry)(OPTION_RETRY),
734 link(cool-write)(OPTION_COOL_WRITE)nl()
735 See also:
736 link(SCTP4-LISTEN)(ADDRESS_SCTP4_LISTEN),
737 link(SCTP6-LISTEN)(ADDRESS_SCTP6_LISTEN),
738 link(TCP-LISTEN)(ADDRESS_TCP_LISTEN),
739 link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT)
740 label(ADDRESS_SCTP4_LISTEN)dit(bf(tt(SCTP4-LISTEN:<port>)))
741 Like link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN), but only supports IPv4
742 protocol.nl()
743 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(SCTP)(GROUP_SCTP),link(RETRY)(GROUP_RETRY) nl()
744 label(ADDRESS_SCTP6_LISTEN)dit(bf(tt(SCTP6-LISTEN:<port>)))
745 Like link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN), but only supports IPv6
746 protocol.nl()
747 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(RETRY)(GROUP_RETRY) nl()
748 label(ADDRESS_SOCKET_CONNECT)dit(bf(tt(SOCKET-CONNECT:<domain>:<protocol>:<remote-address>)))
749 Creates a stream socket using the first and second given socket parameters
750 and tt(SOCK_STREAM) (see man socket\(2)) and connects to the remote-address.
751 The two socket parameters have to be specified by link(int)(TYPE_INT)
752 numbers. Consult your OS documentation and include files to find the
753 appropriate values. The remote-address must be the link(data)(TYPE_DATA)
754 representation of a sockaddr structure without sa_family and (BSD) sa_len
755 components.nl()
756 Please note that you can - beyond the options of the specified groups - also
757 use options of higher level protocols when you apply socat() option
758 link(-g)(option_g).nl()
759 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY)nl()
760 Useful options:
761 link(bind)(OPTION_BIND),
762 link(setsockopt-int)(OPTION_SETSOCKOPT_INT),
763 link(setsockopt-bin)(OPTION_SETSOCKOPT_BIN),
764 link(setsockopt-string)(OPTION_SETSOCKOPT_STRING)
765 nl()
766 See also:
767 link(TCP)(ADDRESS_TCP_CONNECT),
768 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT),
769 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT),
770 link(SOCKET-LISTEN)(ADDRESS_SOCKET_LISTEN),
771 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO)
772 label(ADDRESS_SOCKET_DATAGRAM)dit(bf(tt(SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>)))
773 Creates a datagram socket using the first three given socket parameters (see
774 man socket\(2)) and sends outgoing data to the remote-address. The three
775 socket parameters have to be specified by link(int)(TYPE_INT)
776 numbers. Consult your OS documentation and include files to find the
777 appropriate values. The remote-address must be the link(data)(TYPE_DATA)
778 representation of a sockaddr structure without sa_family and (BSD) sa_len
779 components.nl()
780 Please note that you can - beyond the options of the specified groups - also
781 use options of higher level protocols when you apply socat() option
782 link(-g)(option_g).nl()
783 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(RANGE)(GROUP_RANGE)nl()
784 Useful options:
785 link(bind)(OPTION_BIND),
786 link(range)(OPTION_RANGE),
787 link(setsockopt-int)(OPTION_SETSOCKOPT_INT),
788 link(setsockopt-bin)(OPTION_SETSOCKOPT_BIN),
789 link(setsockopt-string)(OPTION_SETSOCKOPT_STRING)
790 nl()
791 See also:
792 link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM),
793 link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM),
794 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO),
795 link(SOCKET-RECV)(ADDRESS_SOCKET_RECV),
796 link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM)
797 label(ADDRESS_SOCKET_LISTEN)dit(bf(tt(SOCKET-LISTEN:<domain>:<protocol>:<local-address>)))
798 Creates a stream socket using the first and second given socket parameters
799 and tt(SOCK_STREAM) (see man socket\(2)) and waits for incoming connections
800 on local-address. The two socket parameters have to be specified by
801 link(int)(TYPE_INT) numbers. Consult your OS documentation and include files
802 to find the appropriate values. The local-address must be the
803 link(data)(TYPE_DATA) representation of a sockaddr structure without
804 sa_family and (BSD) sa_len components.nl()
805 Please note that you can - beyond the options of the specified groups - also
806 use options of higher level protocols when you apply socat() option
807 link(-g)(option_g).nl()
808 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(RANGE)(GROUP_RANGE),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY)nl()
809 Useful options:
810 link(setsockopt-int)(OPTION_SETSOCKOPT_INT),
811 link(setsockopt-bin)(OPTION_SETSOCKOPT_BIN),
812 link(setsockopt-string)(OPTION_SETSOCKOPT_STRING)
813 nl()
814 See also:
815 link(TCP)(ADDRESS_TCP_LISTEN),
816 link(UDP-CONNECT)(ADDRESS_UDP_LISTEN),
817 link(UNIX-CONNECT)(ADDRESS_UNIX_LISTEN),
818 link(SOCKET-LISTEN)(ADDRESS_SOCKET_CONNECT),
819 link(SOCKET-SENDTO)(ADDRESS_SOCKET_RECVFROM),
820 link(SOCKET-SENDTO)(ADDRESS_SOCKET_RECV)
821 label(ADDRESS_SOCKET_RECV)dit(bf(tt(SOCKET-RECV:<domain>:<type>:<protocol>:<local-address>)))
822 Creates a socket using the three given socket parameters (see man socket\(2))
823 and binds it to <local-address>. Receives arriving data. The three
824 parameters have to be specified by link(int)(TYPE_INT) numbers. Consult your
825 OS documentation and include files to find the appropriate values. The
826 local-address must be the link(data)(TYPE_DATA) representation of a sockaddr
827 structure without sa_family and (BSD) sa_len components.nl()
828 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(RANGE)(GROUP_RANGE)nl()
829 Useful options:
830 link(range)(OPTION_RANGE),
831 link(setsockopt-int)(OPTION_SETSOCKOPT_INT),
832 link(setsockopt-bin)(OPTION_SETSOCKOPT_BIN),
833 link(setsockopt-string)(OPTION_SETSOCKOPT_STRING)
834 nl()
835 See also:
836 link(UDP-RECV)(ADDRESS_UDP_RECV),
837 link(IP-RECV)(ADDRESS_IP_RECV),
838 link(UNIX-RECV)(ADDRESS_UNIX_RECV),
839 link(SOCKET-DATAGRAM)(ADDRESS_SOCKET_DATAGRAM),
840 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO),
841 link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM)
842 label(ADDRESS_SOCKET_RECVFROM)dit(bf(tt(SOCKET-RECVFROM:<domain>:<type>:<protocol>:<local-address>)))
843 Creates a socket using the three given socket parameters (see man socket\(2))
844 and binds it to <local-address>. Receives arriving data and sends replies
845 back to the sender. The first three parameters have to be specified as
846 link(int)(TYPE_INT) numbers. Consult your OS documentation and include files
847 to find the appropriate values. The local-address must be the
848 link(data)(TYPE_DATA) representation of a sockaddr structure without
849 sa_family and (BSD) sa_len components.nl()
850 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE)nl()
851 Useful options:
852 link(fork)(OPTION_FORK),
853 link(range)(OPTION_RANGE),
854 link(setsockopt-int)(OPTION_SETSOCKOPT_INT),
855 link(setsockopt-bin)(OPTION_SETSOCKOPT_BIN),
856 link(setsockopt-string)(OPTION_SETSOCKOPT_STRING)
857 nl()
858 See also:
859 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM),
860 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM),
861 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM),
862 link(SOCKET-DATAGRAM)(ADDRESS_SOCKET_DATAGRAM),
863 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO),
864 link(SOCKET-RECV)(ADDRESS_SOCKET_RECV)
865 label(ADDRESS_SOCKET_SENDTO)dit(bf(tt(SOCKET-SENDTO:<domain>:<type>:<protocol>:<remote-address>)))
866 Creates a socket using the three given socket parameters (see man
867 socket\(2)). Sends outgoing data to the given address and receives replies.
868 The three parameters have to be specified as link(int)(TYPE_INT)
869 numbers. Consult your OS documentation and include files to find the
870 appropriate values. The remote-address must be the link(data)(TYPE_DATA)
871 representation of a sockaddr structure without sa_family and (BSD) sa_len
872 components.nl()
873 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET)nl()
874 Useful options:
875 link(bind)(OPTION_BIND),
876 link(setsockopt-int)(OPTION_SETSOCKOPT_INT),
877 link(setsockopt-bin)(OPTION_SETSOCKOPT_BIN),
878 link(setsockopt-string)(OPTION_SETSOCKOPT_STRING)
879 nl()
880 See also:
881 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO),
882 link(IP-SENDTO)(ADDRESS_IP_SENDTO),
883 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO),
884 link(SOCKET-DATAGRAM)(ADDRESS_SOCKET_DATAGRAM),
885 link(SOCKET-RECV)(ADDRESS_SOCKET_RECV)
886 link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM)
887 label(ADDRESS_SOCKS4)dit(bf(tt(SOCKS4:<socks-server>:<host>:<port>)))
888 Connects via <socks-server> [link(IP address)(TYPE_IP_ADDRESS)]
889 to <host> [link(IPv4 address)(TYPE_IPV4_ADDRESS)]
890 on <port> [link(TCP service)(TYPE_TCP_SERVICE)],
891 using socks version 4 protocol over IP version 4 or 6 depending on address specification, name resolution, or option
892 link(pf)(OPTION_PROTOCOL_FAMILY) (link(example)(EXAMPLE_ADDRESS_SOCKS4)).nl()
893 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(SOCKS4)(GROUP_SOCKS),link(RETRY)(GROUP_RETRY) nl()
894 Useful options:
895 link(socksuser)(OPTION_SOCKSUSER),
896 link(socksport)(OPTION_SOCKSPORT),
897 link(sourceport)(OPTION_SOURCEPORT),
898 link(pf)(OPTION_PROTOCOL_FAMILY),
899 link(retry)(OPTION_RETRY)nl()
900 See also:
901 link(SOCKS4A)(ADDRESS_SOCKS4A),
902 link(PROXY)(ADDRESS_PROXY_CONNECT),
903 link(TCP)(ADDRESS_TCP_CONNECT)
904 label(ADDRESS_SOCKS4A)dit(bf(tt(SOCKS4A:<socks-server>:<host>:<port>)))
905 like link(SOCKS4)(ADDRESS_SOCKS4), but uses socks protocol version 4a, thus
906 leaving host name resolution to the socks server.nl()
907 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(SOCKS4)(GROUP_SOCKS),link(RETRY)(GROUP_RETRY) nl()
908 label(ADDRESS_STDERR)dit(bf(tt(STDERR)))
909 Uses file descriptor 2.nl()
910 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl()
911 See also: link(FD)(ADDRESS_FD)
912 label(ADDRESS_STDIN)dit(bf(tt(STDIN)))
913 Uses file descriptor 0.nl()
914 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl()
915 Useful options:
916 link(readbytes)(OPTION_READBYTES)nl()
917 See also: link(FD)(ADDRESS_FD)
918 label(ADDRESS_STDIO)dit(bf(tt(STDIO)))
919 Uses file descriptor 0 for reading, and 1 for writing.nl()
920 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl()
921 Useful options:
922 link(readbytes)(OPTION_READBYTES)nl()
923 See also: link(FD)(ADDRESS_FD)
924 label(ADDRESS_STDOUT)dit(bf(tt(STDOUT)))
925 Uses file descriptor 1.nl()
926 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl()
927 See also: link(FD)(ADDRESS_FD)
928 label(ADDRESS_SYSTEM)dit(bf(tt(SYSTEM:<command-line>)))
929 Is an alias for link(SYSTEM2)(ADDRESS_SYSTEM2)
930 label(ADDRESS_SYSTEM1)dit(bf(tt(SYSTEM1:<command-line>)))
931 This is a variation of the link(SYSTEM2)(ADDRESS_SYSTEM2) address that provides
932 unidirectional communication within an address chain: socat() connects the
933 program's stdin to its left neighbor and its stdout to its right neighbor.
934 nl()
935 See also: link(EXEC1)(ADDRESS_EXEC1)
936 label(ADDRESS_SYSTEM2)dit(bf(tt(SYSTEM2:<shell-command>)))
937 Forks a sub process that establishes communication with its parent process
938 and invokes the specified program with code(system()). Please note that
939 <shell-command> [link(string)(TYPE_STRING)] must
940 not contain unprotected ',' or "%", and that shell meta characters may have
941 to be escaped.
942 After successful program start, socat() writes data to stdin of the
943 process and reads from its stdout.
944 This address may be used as an endpoint address where socat() writes data to
945 stdin of the process and reads from its stdout using two unixdomain()
946 sockets generated by code(socketpair()) per default
947 (link(example)(EXAMPLE_ADDRESS_EXEC)), or as an inter address where
948 socat() connects the program's stdio to its left neighbor and its file
949 descriptors 3 and 4 to its right neighbor. nl()
950 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(EXEC)(GROUP_EXEC),link(FORK)(GROUP_FORK),link(TERMIOS)(GROUP_TERMIOS) nl()
951 Useful options:
952 link(path)(OPTION_PATH),
953 link(fdin)(OPTION_FDIN),
954 link(fdout)(OPTION_FDOUT),
955 link(chroot)(OPTION_CHROOT),
956 link(su)(OPTION_SUBSTUSER),
957 link(su-d)(OPTION_SUBSTUSER_DELAYED),
958 link(nofork)(OPTION_NOFORK),
959 link(commtype)(OPTION_COMMTYPE),
960 link(stderr)(OPTION_STDERR),
961 link(ctty)(OPTION_CTTY),
962 link(setsid)(OPTION_SETSID),
963 link(sigint)(OPTION_SIGINT),
964 link(sigquit)(OPTION_SIGQUIT)nl()
965 See also: link(EXEC)(ADDRESS_EXEC)
966 label(ADDRESS_TCP_CONNECT)dit(bf(tt(TCP:<host>:<port>)))
967 Connects to <port> [link(TCP service)(TYPE_TCP_SERVICE)] on
968 <host> [link(IP address)(TYPE_IP_ADDRESS)] using TCP/IP version 4 or 6
969 depending on address specification, name resolution, or option
970 link(pf)(OPTION_PROTOCOL_FAMILY).nl()
971 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl()
972 Useful options:
973 link(crnl)(OPTION_CRNL),
974 link(bind)(OPTION_BIND),
975 link(pf)(OPTION_PROTOCOL_FAMILY),
976 link(connect-timeout)(OPTION_CONNECT_TIMEOUT),
977 link(tos)(OPTION_TOS),
978 link(mtudiscover)(OPTION_MTUDISCOVER),
979 link(mss)(OPTION_MSS),
980 link(nodelay)(OPTION_NODELAY),
981 link(nonblock)(OPTION_NONBLOCK),
982 link(sourceport)(OPTION_SOURCEPORT),
983 link(retry)(OPTION_RETRY),
984 link(readbytes)(OPTION_READBYTES)nl()
985 See also:
986 link(TCP4)(ADDRESS_TCP4_CONNECT),
987 link(TCP6)(ADDRESS_TCP6_CONNECT),
988 link(TCP-LISTEN)(ADDRESS_TCP_LISTEN),
989 link(UDP)(ADDRESS_UDP_CONNECT),
990 link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT),
991 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT)
992 label(ADDRESS_TCP4_CONNECT)dit(bf(tt(TCP4:<host>:<port>)))
993 Like link(TCP)(ADDRESS_TCP_CONNECT), but only supports IPv4 protocol (link(example)(EXAMPLE_ADDRESS_TCP4_CONNECT)).nl()
994 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl()
995 label(ADDRESS_TCP6_CONNECT)dit(bf(tt(TCP6:<host>:<port>)))
996 Like link(TCP)(ADDRESS_TCP_CONNECT), but only supports IPv6 protocol.nl()
997 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl()
998 label(ADDRESS_TCP_LISTEN)dit(bf(tt(TCP-LISTEN:<port>)))
999 Listens on <port> [link(TCP service)(TYPE_TCP_SERVICE)] and accepts a
1000 TCP/IP connection. The IP version is 4 or the one specified with
1001 address option link(pf)(OPTION_PROTOCOL_FAMILY), socat() option
1002 (link(-4)(option_4), link(-6)(option_6)), or environment variable link(SOCAT_DEFAULT_LISTEN_IP)(ENV_SOCAT_DEFAULT_LISTEN_IP).
1003 Note that opening
1004 this address usually blocks until a client connects.nl()
1005 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl()
1006 Useful options:
1007 link(crnl)(OPTION_CRNL),
1008 link(fork)(OPTION_FORK),
1009 link(bind)(OPTION_BIND),
1010 link(range)(OPTION_RANGE),
1011 link(tcpwrap)(OPTION_TCPWRAPPERS),
1012 link(pf)(OPTION_PROTOCOL_FAMILY),
1013 link(max-children)(OPTION_MAX_CHILDREN),
1014 link(backlog)(OPTION_BACKLOG),
1015 link(mss)(OPTION_MSS),
1016 link(su)(OPTION_SUBSTUSER),
1017 link(reuseaddr)(OPTION_REUSEADDR),
1018 link(retry)(OPTION_RETRY),
1019 link(cool-write)(OPTION_COOL_WRITE)nl()
1020 See also:
1021 link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN),
1022 link(TCP6-LISTEN)(ADDRESS_TCP6_LISTEN),
1023 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN),
1024 link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN),
1025 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN),
1026 link(OPENSSL-LISTEN)(ADDRESS_OPENSSL_LISTEN),
1027 link(TCP-CONNECT)(ADDRESS_TCP_CONNECT)
1028 label(ADDRESS_TCP4_LISTEN)dit(bf(tt(TCP4-LISTEN:<port>)))
1029 Like link(TCP-LISTEN)(ADDRESS_TCP_LISTEN), but only supports IPv4
1030 protocol (link(example)(EXAMPLE_ADDRESS_TCP4_LISTEN)).nl()
1031 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl()
1032 label(ADDRESS_TCP6_LISTEN)dit(bf(tt(TCP6-LISTEN:<port>)))
1033 Like link(TCP-LISTEN)(ADDRESS_TCP_LISTEN), but only supports IPv6
1034 protocol.nl()
1035 Additional useful option:
1036 link(ipv6only)(OPTION_IPV6_V6ONLY)nl()
1037 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl()
1038 label(ADDRESS_TUN)dit(bf(tt(TUN[:<if-addr>/<bits>])))
1039 Creates a Linux TUN/TAP device and optionally assignes it the address and
1040 netmask given by the parameters. The resulting network interface is almost
1041 ready for use by other processes; socat serves its "wire side". This address
1042 requires read and write access to the tunnel cloning device, usually
1043 code(/dev/net/tun), as well as permission to set some tt(ioctl()s).
1044 bf(Option iff-up is required to immediately activate the interface!)nl()
1045 Option groups: link(FD)(GROUP_FD),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN),link(TUN)(GROUP_TUN) nl()
1046 Useful options:
1047 link(iff-up)(OPTION_IFF_UP),
1048 link(tun-device)(OPTION_TUN_DEVICE),
1049 link(tun-name)(OPTION_TUN_NAME),
1050 link(tun-type)(OPTION_TUN_TYPE),
1051 link(iff-no-pi)(OPTION_IFF_NO_PI) nl()
1052 See also:
1053 link(ip-recv)(ADDRESS_IP_RECV)
1054 label(ADDRESS_UDP_CONNECT)dit(bf(tt(UDP:<host>:<port>)))
1055 Connects to <port> [link(UDP service)(TYPE_UDP_SERVICE)] on
1056 <host> [link(IP address)(TYPE_IP_ADDRESS)] using UDP/IP version 4 or 6
1057 depending on address specification, name resolution, or option
1058 link(pf)(OPTION_PROTOCOL_FAMILY).nl()
1059 Please note that,
1060 due to UDP protocol properties, no real connection is established; data has
1061 to be sent for `connecting' to the server, and no end-of-file condition can
1062 be transported.nl()
1063 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl()
1064 Useful options:
1065 link(ttl)(OPTION_TTL),
1066 link(tos)(OPTION_TOS),
1067 link(bind)(OPTION_BIND),
1068 link(sourceport)(OPTION_SOURCEPORT),
1069 link(pf)(OPTION_PROTOCOL_FAMILY)nl()
1070 See also:
1071 link(UDP4)(ADDRESS_UDP4_CONNECT),
1072 link(UDP6)(ADDRESS_UDP6_CONNECT),
1073 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN),
1074 link(TCP)(ADDRESS_TCP_CONNECT),
1075 link(IP)(ADDRESS_IP_SENDTO)
1076 label(ADDRESS_UDP4_CONNECT)dit(bf(tt(UDP4:<host>:<port>)))
1077 Like link(UDP)(ADDRESS_UDP_CONNECT), but only supports IPv4 protocol.nl()
1078 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4) nl()
1079 label(ADDRESS_UDP6_CONNECT)dit(bf(tt(UDP6:<host>:<port>)))
1080 Like link(UDP)(ADDRESS_UDP_CONNECT), but only supports IPv6 protocol.nl()
1081 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6) nl()
1082 label(ADDRESS_UDP_DATAGRAM)dit(bf(tt(UDP-DATAGRAM:<address>:<port>)))
1083 Sends outgoing data to the specified address which may in particular be a
1084 broadcast or multicast address. Packets arriving on the local socket are
1085 checked for the correct remote port and if their source addresses match
1086 link(RANGE)(OPTION_RANGE) or link(TCPWRAP)(OPTION_TCPWRAPPERS)
1087 options. This address type can for example be used for implementing
1088 symmetric or asymmetric broadcast or multicast communications.nl()
1089 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl()
1090 Useful options:
1091 link(bind)(OPTION_BIND),
1092 link(range)(OPTION_RANGE),
1093 link(tcpwrap)(OPTION_TCPWRAPPERS),
1094 link(broadcast)(OPTION_SO_BROADCAST),
1095 link(ip-multicast-loop)(OPTION_IP_MULTICAST_LOOP),
1096 link(ip-multicast-ttl)(OPTION_IP_MULTICAST_TTL),
1097 link(ip-multicast-if)(OPTION_IP_MULTICAST_IF),
1098 link(ip-add-membership)(OPTION_IP_ADD_MEMBERSHIP),
1099 link(ttl)(OPTION_TTL),
1100 link(tos)(OPTION_TOS),
1101 link(sourceport)(OPTION_SOURCEPORT),
1102 link(pf)(OPTION_PROTOCOL_FAMILY)nl()
1103 See also:
1104 link(UDP4-DATAGRAM)(ADDRESS_UDP4_DATAGRAM),
1105 link(UDP6-DATAGRAM)(ADDRESS_UDP6_DATAGRAM),
1106 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO),
1107 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM),
1108 link(UDP-RECV)(ADDRESS_UDP_RECV),
1109 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT),
1110 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN),
1111 link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM)
1112 label(ADDRESS_UDP4_DATAGRAM)dit(bf(tt(UDP4-DATAGRAM:<address>:<port>)))
1113 Like link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM), but only supports IPv4
1114 protocol (link(example1)(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT),
1115 link(example2)(EXAMPLE_ADDRESS_UDP4_MULTICAST)).nl()
1116 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4), link(RANGE)(GROUP_RANGE)
1117 label(ADDRESS_UDP6_DATAGRAM)dit(bf(tt(UDP6-DATAGRAM:<address>:<port>)))
1118 Like link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM), but only supports IPv6
1119 protocol.nl()
1120 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE)
1121 label(ADDRESS_UDP_LISTEN)dit(bf(tt(UDP-LISTEN:<port>)))
1122 Waits for a UDP/IP packet arriving on <port>
1123 [link(UDP service)(TYPE_UDP_SERVICE)] and `connects' back to sender.
1124 The accepted IP version is 4 or the one specified with option
1125 link(pf)(OPTION_PROTOCOL_FAMILY).
1126 Please note that,
1127 due to UDP protocol properties, no real connection is established; data has
1128 to arrive from the peer first, and no end-of-file condition can be
1129 transported. Note that opening
1130 this address usually blocks until a client connects.nl()
1131 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl()
1132 Useful options:
1133 link(fork)(OPTION_FORK),
1134 link(bind)(OPTION_BIND),
1135 link(range)(OPTION_RANGE),
1136 link(pf)(OPTION_PROTOCOL_FAMILY) nl()
1137 See also:
1138 link(UDP)(ADDRESS_UDP_CONNECT),
1139 link(UDP4-LISTEN)(ADDRESS_UDP4_LISTEN),
1140 link(UDP6-LISTEN)(ADDRESS_UDP6_LISTEN),
1141 link(TCP-LISTEN)(ADDRESS_TCP_LISTEN)
1142 label(ADDRESS_UDP4_LISTEN)dit(bf(tt(UDP4-LISTEN:<port>)))
1143 Like link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), but only support IPv4
1144 protocol.nl()
1145 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4) nl()
1146 label(ADDRESS_UDP6_LISTEN)dit(bf(tt(UDP6-LISTEN:<port>)))
1147 Like link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), but only support IPv6
1148 protocol.nl()
1149 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP6)(GROUP_IP6) nl()
1150 label(ADDRESS_UDP_SENDTO)dit(bf(tt(UDP-SENDTO:<host>:<port>)))
1151 Communicates with the specified peer socket, defined by <port> [link(UDP
1152 service)(TYPE_UDP_SERVICE)] on
1153 <host> [link(IP address)(TYPE_IP_ADDRESS)], using UDP/IP version 4 or 6
1154 depending on address specification, name resolution, or option
1155 link(pf)(OPTION_PROTOCOL_FAMILY). It sends packets to and receives packets
1156 from that peer socket only.
1157 This address effectively implements a datagram client.
1158 It works well with socat() UDP-RECVFROM and UDP-RECV address peers.nl()
1159 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl()
1160 Useful options:
1161 link(ttl)(OPTION_TTL),
1162 link(tos)(OPTION_TOS),
1163 link(bind)(OPTION_BIND),
1164 link(sourceport)(OPTION_SOURCEPORT),
1165 link(pf)(OPTION_PROTOCOL_FAMILY)nl()
1166 See also:
1167 link(UDP4-SENDTO)(ADDRESS_UDP4_SENDTO),
1168 link(UDP6-SENDTO)(ADDRESS_UDP6_SENDTO),
1169 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM),
1170 link(UDP-RECV)(ADDRESS_UDP_RECV),
1171 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT),
1172 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN),
1173 link(IP-SENDTO)(ADDRESS_IP_SENDTO)
1174 label(ADDRESS_UDP4_SENDTO)dit(bf(tt(UDP4-SENDTO:<host>:<port>)))
1175 Like link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), but only supports IPv4
1176 protocol.nl()
1177 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4)
1178 label(ADDRESS_UDP6_SENDTO)dit(bf(tt(UDP6-SENDTO:<host>:<port>)))
1179 Like link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), but only supports IPv6
1180 protocol.nl()
1181 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6)
1182  
1183 label(ADDRESS_UDP_RECVFROM)dit(bf(tt(UDP-RECVFROM:<port>)))
1184 Creates a UDP socket on <port> [link(UDP service)(TYPE_UDP_SERVICE)] using
1185 UDP/IP version 4 or 6
1186 depending on option link(pf)(OPTION_PROTOCOL_FAMILY).
1187 It receives one packet from an unspecified peer and may send one or more
1188 answer packets to that peer. This mode is particularly useful with fork
1189 option
1190 where each arriving packet - from arbitrary peers - is handled by its own sub
1191 process. This allows a behaviour similar to typical UDP based servers like ntpd
1192 or named. This address works well with socat() UDP-SENDTO address peers.nl()
1193 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl()
1194 Useful options:
1195 link(fork)(OPTION_FORK),
1196 link(ttl)(OPTION_TTL),
1197 link(tos)(OPTION_TOS),
1198 link(bind)(OPTION_BIND),
1199 link(sourceport)(OPTION_SOURCEPORT),
1200 link(pf)(OPTION_PROTOCOL_FAMILY)nl()
1201 See also:
1202 link(UDP4-RECVFROM)(ADDRESS_UDP4_RECVFROM),
1203 link(UDP6-RECVFROM)(ADDRESS_UDP6_RECVFROM),
1204 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO),
1205 link(UDP-RECV)(ADDRESS_UDP_RECV),
1206 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT),
1207 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN),
1208 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM),
1209 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM)
1210 label(ADDRESS_UDP4_RECVFROM)dit(bf(tt(UDP4-RECVFROM:<port>)))
1211 Like link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), but only supports IPv4 protocol.nl()
1212 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE)
1213 label(ADDRESS_UDP6_RECVFROM)dit(bf(tt(UDP6-RECVFROM:<port>)))
1214 Like link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), but only supports IPv6 protocol.nl()
1215 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE)
1216  
1217 label(ADDRESS_UDP_RECV)dit(bf(tt(UDP-RECV:<port>)))
1218 Creates a UDP socket on <port> [link(UDP service)(TYPE_UDP_SERVICE)] using UDP/IP version 4 or 6
1219 depending on option link(pf)(OPTION_PROTOCOL_FAMILY).
1220 It receives packets from multiple unspecified peers and merges the data.
1221 No replies are possible. It works well with, e.g., socat() UDP-SENDTO address peers; it behaves similar to a syslog server.nl()
1222 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl()
1223 Useful options:
1224 link(fork)(OPTION_FORK),
1225 link(pf)(OPTION_PROTOCOL_FAMILY),
1226 link(bind)(OPTION_BIND),
1227 link(sourceport)(OPTION_SOURCEPORT),
1228 link(ttl)(OPTION_TTL),
1229 link(tos)(OPTION_TOS)nl()
1230 See also:
1231 link(UDP4-RECV)(ADDRESS_UDP4_RECV),
1232 link(UDP6-RECV)(ADDRESS_UDP6_RECV),
1233 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO),
1234 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM),
1235 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT),
1236 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN),
1237 link(IP-RECV)(ADDRESS_IP_RECV),
1238 link(UNIX-RECV)(ADDRESS_UNIX_RECV)
1239 label(ADDRESS_UDP4_RECV)dit(bf(tt(UDP4-RECV:<port>)))
1240 Like link(UDP-RECV)(ADDRESS_UDP_RECV), but only supports IPv4 protocol.nl()
1241 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(RANGE)(GROUP_RANGE)
1242 label(ADDRESS_UDP6_RECV)dit(bf(tt(UDP6-RECV:<port>)))
1243 Like link(UDP-RECV)(ADDRESS_UDP_RECV), but only supports IPv6 protocol.nl()
1244 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE)
1245  
1246 label(ADDRESS_UNIX_CONNECT)dit(bf(tt(UNIX-CONNECT:<filename>)))
1247 Connects to link(<filename>)(TYPE_FILENAME) assuming it is a unixdomain()
1248 socket.
1249 If <filename> does not exist, this is an error;
1250 if <filename> is not a unixdomain() socket, this is an error;
1251 if <filename> is a unixdomain() socket, but no process is listening, this is
1252 an error.nl()
1253 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(RETRY)(GROUP_RETRY),link(UNIX)(GROUP_SOCK_UNIX) nl())
1254 Useful options:
1255 link(bind)(OPTION_BIND)nl()
1256 See also:
1257 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN),
1258 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO),
1259 link(TCP)(ADDRESS_TCP_CONNECT)
1260  
1261 label(ADDRESS_UNIX_LISTEN)dit(bf(tt(UNIX-LISTEN:<filename>)))
1262 Listens on link(<filename>)(TYPE_FILENAME) using a unixdomain() stream
1263 socket and accepts a connection.
1264 If <filename> exists and is not a socket, this is an error.
1265 If <filename> exists and is a unixdomain() socket, binding to the address
1266 fails (use option link(unlink-early)(OPTION_UNLINK_EARLY)!).
1267 Note that opening this address usually blocks until a client connects.
1268 Beginning with socat() version 1.4.3, the file system entry is removed when
1269 this address is closed (but see option link(unlink-close)(OPTION_UNLINK_CLOSE)) (link(example)(EXAMPLE_ADDRESS_UNIX_LISTEN)).nl()
1270 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY),link(UNIX)(GROUP_SOCK_UNIX) nl()
1271 Useful options:
1272 link(fork)(OPTION_FORK),
1273 link(umask)(OPTION_UMASK),
1274 link(mode)(OPTION_MODE),
1275 link(user)(OPTION_USER),
1276 link(group)(OPTION_GROUP),
1277 link(unlink-early)(OPTION_UNLINK_EARLY)nl()
1278 See also:
1279 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT),
1280 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM),
1281 link(UNIX-RECV)(ADDRESS_UNIX_RECV),
1282 link(TCP-LISTEN)(ADDRESS_TCP4_LISTEN)
1283  
1284 label(ADDRESS_UNIX_SENDTO)dit(bf(tt(UNIX-SENDTO:<filename>)))
1285 Communicates with the specified peer socket, defined by [link(<filename>)(TYPE_FILENAME)] assuming it is a unixdomain() datagram socket.
1286 It sends packets to and receives packets from that peer socket only.
1287 Please note that it might be neccessary to link(bind)(OPTION_BIND) the
1288 local socket to an address (e.g. tt(/tmp/sock1), which must not exist
1289 before).
1290 This address type works well with socat() UNIX-RECVFROM and UNIX-RECV address
1291 peers.nl()
1292 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),
1293 link(NAMED)(GROUP_NAMED),link(UNIX)(GROUP_SOCK_UNIX)nl()
1294 Useful options:
1295 link(bind)(OPTION_BIND)nl()
1296 See also:
1297 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM),
1298 link(UNIX-RECV)(ADDRESS_UNIX_RECV),
1299 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT),
1300 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO),
1301 link(IP-SENDTO)(ADDRESS_IP_SENDTO)
1302  
1303 label(ADDRESS_UNIX_RECVFROM)dit(bf(tt(UNIX-RECVFROM:<filename>)))
1304 Creates a unixdomain() datagram socket [link(<filename>)(TYPE_FILENAME)].
1305 Receives one packet and may send one or more answer packets to that peer.
1306 This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process.
1307 This address works well with socat() UNIX-SENDTO address peers.nl()
1308 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),
1309 link(NAMED)(GROUP_NAMED),link(CHILD)(GROUP_CHILD),
1310 link(UNIX)(GROUP_SOCK_UNIX) nl()
1311 Useful options:
1312 link(fork)(OPTION_FORK)nl()
1313 See also:
1314 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO),
1315 link(UNIX-RECV)(ADDRESS_UNIX_RECV),
1316 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN),
1317 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM),
1318 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM)
1319  
1320 label(ADDRESS_UNIX_RECV)dit(bf(tt(UNIX-RECV:<filename>)))
1321 Creates a unixdomain() datagram socket [link(<filename>)(TYPE_FILENAME)].
1322 Receives packets from multiple unspecified peers and merges the data.
1323 No replies are possible. It can be, e.g., addressed by socat() UNIX-SENDTO address peers.
1324 It behaves similar to a syslog server.
1325 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(UNIX)(GROUP_SOCK_UNIX) nl()
1326 See also:
1327 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO),
1328 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM),
1329 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN),
1330 link(UDP-RECV)(ADDRESS_UDP_RECV),
1331 link(IP-RECV)(ADDRESS_IP_RECV)
1332  
1333 label(ADDRESS_UNIX_CLIENT)dit(bf(tt(UNIX-CLIENT:<filename>)))
1334 Communicates with the specified peer socket, defined by
1335 [link(<filename>)(TYPE_FILENAME)] assuming it is a unixdomain() socket.
1336 It first tries to connect and, if that fails, assumes it is a datagram
1337 socket, thus supporting both types.nl()
1338 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(UNIX)(GROUP_SOCK_UNIX) nl()
1339 Useful options:
1340 link(bind)(OPTION_BIND)nl()
1341 See also:
1342 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT),
1343 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO),
1344 link(GOPEN)(ADDRESS_GOPEN)
1345  
1346 dit(bf(tt(ABSTRACT-CONNECT:<string>)))
1347 dit(bf(tt(ABSTRACT-LISTEN:<string>)))
1348 dit(bf(tt(ABSTRACT-SENDTO:<string>)))
1349 dit(bf(tt(ABSTRACT-RECVFROM:<string>)))
1350 dit(bf(tt(ABSTRACT-RECV:<string>)))
1351 dit(bf(tt(ABSTRACT-CLIENT:<string>)))
1352 The ABSTRACT addresses are almost identical to the related UNIX addresses
1353 except that they do not address file system based sockets but an alternate
1354 unixdomain() address space. To archieve this the socket address strings are
1355 prefixed with "\0" internally. This feature is available (only?) on Linux.
1356 Option groups are the same as with the related UNIX addresses, except that
1357 the ABSTRACT addresses are not member of the NAMED group.
1358 enddit()
1359  
1360  
1361 label(ADDRESS_OPTIONS)
1362 manpagesection(ADDRESS OPTIONS)
1363  
1364 Address options can be applied to address specifications to influence the
1365 process of opening the addresses and the
1366 properties of the resulting data channels.
1367  
1368 For technical reasons not every option can be
1369 applied to every address type; e.g., applying a socket option to a regular file
1370 will fail. To catch most useless combinations as early as in the open phase,
1371 the concept of em(option groups) was introduced. Each option belongs to one
1372 or more option groups. Options can be used only with address types that support
1373 at least one of their option groups (but see link(option -g)(option_g)).
1374  
1375 Address options have data types that their values must conform to.
1376 Every address option consists of just a keyword or a keyword followed by
1377 "=value", where value must conform to the options type.
1378 COMMENT(Options that trigger a call with
1379 trivial parameters are described with type BOOL which might be misleading.)
1380 Some address options manipulate parameters of system calls;
1381 e.g., option sync sets the code(O_SYNC) flag with the code(open()) call.
1382 Other options cause a system or library call; e.g., with option `ttl=value'
1383 the code(setsockopt(fd, SOL_IP, IP_TTL, value, sizeof(int))) call is applied.
1384 Other
1385 options set internal socat() variables that are used during data transfer;
1386 e.g., `crnl' causes explicit character conversions.
1387 A few options have more complex implementations; e.g., su-d
1388 (substuser-delayed) inquires some user and group infos, stores them, and
1389 applies them later after a possible code(chroot()) call.
1390  
1391 If multiple options are given to an address, their sequence in the address specification has (almost) no
1392 effect on the sequence of their execution/application. Instead, socat() has
1393 built in an em(option phase) model that tries to bring the options in a useful
1394 order. Some options exist in different forms (e.g.,
1395 unlink, unlink-early, unlink-late) to control the time of their execution.
1396  
1397 If the same option is specified more than once within one address
1398 specification, with equal or different values, the effect depends on the kind of option. Options
1399 resulting in function calls like code(setsockopt()) cause multiple
1400 invocations. With options that set parameters for a required call like
1401 code(open())
1402 or set internal flags, the value of the last option occurrence is effective.
1403  
1404 The existence or semantics of many options are system dependent. Socat()
1405 usually does NOT try to emulate missing libc or kernel features, it just
1406 provides an
1407 interface to the underlying system. So, if an operating system lacks a feature,
1408 the related option is simply not available on this platform.
1409  
1410 The following paragraphs introduce just the more common address options. For
1411 a more comprehensive reference and to find information about canonical option
1412 names, alias names, option phases, and platforms see file file(xio.help).
1413 nl() nl()
1414  
1415 startdit()enddit()nl()
1416  
1417  
1418 label(GROUP_FD)em(bf(FD option group))
1419  
1420 This option group contains options that are applied to a unix()
1421 style file descriptor, no matter how it was generated.
1422 Because all current socat() address types are file descriptor based, these
1423 options may be applied to any address. nl()
1424 Note: Some of these options are also member of another option group, that
1425 provides an other, non-fd based mechanism.
1426 For these options, it depends on the actual address type and its option groups
1427 which mechanism is used. The second, non-fd based mechanism is prioritized.
1428 startdit()
1429 label(OPTION_CLOEXEC)dit(bf(tt(cloexec=<bool>)))
1430 Sets the code(FD_CLOEXEC) flag with the code(fcntl()) system call to value
1431 link(<bool>)(TYPE_BOOL). If set,
1432 the file descriptor is closed on code(exec()) family function calls. Socat()
1433 internally handles
1434 this flag for the fds it controls, so in most cases there will be no need to
1435 apply this option.
1436 label(OPTION_SETLK_WR)dit(bf(tt(setlk)))
1437 Tries to set a discretionary write lock to the whole file using the code(fcntl(fd,
1438 F_SETLK, ...)) system call. If the file is already locked, this call results
1439 in an error.
1440 On Linux, when the file permissions for group are "S" (g-x,g+s), and the
1441 file system is locally mounted with the "mand" option, the lock is
1442 mandatory, i.e. prevents other processes from opening the file.
1443 label(OPTION_SETLKW_WR)dit(bf(tt(setlkw)))
1444 Tries to set a discretionary waiting write lock to the whole file using the
1445 code(fcntl(fd, F_SETLKW, ...)) system call. If the file is already locked,
1446 this call blocks.
1447 See option link(setlk)(OPTION_SETLK_WR) for information about making this
1448 lock mandatory.
1449 label(OPTION_SETLK_RD)dit(bf(tt(setlk-rd)))
1450 Tries to set a discretionary read lock to the whole file using the code(fcntl(fd,
1451 F_SETLK, ...)) system call. If the file is already write locked, this call
1452 results in an error.
1453 See option link(setlk)(OPTION_SETLK_WR) for information about making this
1454 lock mandatory.
1455 label(OPTION_SETLKW_RD)dit(bf(tt(setlkw-rd)))
1456 Tries to set a discretionary waiting read lock to the whole file using the
1457 code(fcntl(fd, F_SETLKW, ...)) system call. If the file is already write
1458 locked, this call blocks.
1459 See option link(setlk)(OPTION_SETLK_WR) for information about making this
1460 lock mandatory.
1461 label(OPTION_FLOCK_EX)dit(bf(tt(flock-ex)))
1462 Tries to set a blocking exclusive advisory lock to the file using the
1463 code(flock(fd, LOCK_EX)) system call. Socat() hangs in this call if the file
1464 is locked by another process.
1465 label(OPTION_FLOCK_EX_NB)dit(bf(tt(flock-ex-nb)))
1466 Tries to set a nonblocking exclusive advisory lock to the file using the
1467 code(flock(fd, LOCK_EX|LOCK_NB)) system call. If the file is already locked,
1468 this option results in an error.
1469 label(OPTION_FLOCK_SH)dit(bf(tt(flock-sh)))
1470 Tries to set a blocking shared advisory lock to the file using the
1471 code(flock(fd, LOCK_SH)) system call. Socat() hangs in this call if the file
1472 is locked by another process.
1473 label(OPTION_FLOCK_SH_NB)dit(bf(tt(flock-sh-nb)))
1474 Tries to set a nonblocking shared advisory lock to the file using the
1475 code(flock(fd, LOCK_SH|LOCK_NB)) system call. If the file is already locked,
1476 this option results in an error.
1477 label(OPTION_LOCK)dit(bf(tt(lock)))
1478 Sets a blocking lock on the file. Uses the setlk or flock mechanism
1479 depending on availability on the particular platform. If both are available,
1480 the POSIX variant (setlkw) is used.
1481 label(OPTION_USER)dit(bf(tt(user=<user>)))
1482 Sets the link(<user>)(TYPE_USER) (owner) of the stream.
1483 If the address is member of the NAMED option group,
1484 socat() uses the code(chown()) system call after opening the
1485 file or binding to the unixdomain() socket (race condition!).
1486 Without filesystem entry, socat() sets the user of the stream
1487 using the code(fchown()) system call.
1488 These calls might require root privilege.
1489 label(OPTION_USER_LATE)dit(bf(tt(user-late=<user>)))
1490 Sets the owner of the fd to link(<user>)(TYPE_USER) with the code(fchown())
1491 system call after opening
1492 or connecting the channel.
1493 This is useful only on file system entries.
1494 label(OPTION_GROUP)dit(bf(tt(group=<group>)))
1495 Sets the link(<group>)(TYPE_GROUP) of the stream.
1496 If the address is member of the NAMED option group,
1497 socat() uses the code(chown()) system call after opening the
1498 file or binding to the unixdomain() socket (race condition!).
1499 Without filesystem entry, socat() sets the group of the stream
1500 with the code(fchown()) system call.
1501 These calls might require group membership or root privilege.
1502 label(OPTION_GROUP_LATE)dit(bf(tt(group-late=<group>)))
1503 Sets the group of the fd to link(<group>)(TYPE_GROUP) with the
1504 code(fchown()) system call after opening
1505 or connecting the channel.
1506 This is useful only on file system entries.
1507 label(OPTION_MODE)dit(bf(tt(mode=<mode>)))
1508 Sets the <mode> [link(mode_t)(TYPE_MODE_T)] (permissions) of the stream.
1509 If the address is member of the NAMED option group and
1510 uses the code(open()) or code(creat()) call, the mode is applied with these.
1511 If the address is member of the NAMED option group without using these
1512 system calls, socat() uses the code(chmod()) system call after opening the
1513 filesystem entry or binding to the unixdomain() socket (race condition!).
1514 Otherwise, socat() sets the mode of the stream
1515 using code(fchmod()).
1516 These calls might require ownership or root privilege.
1517 label(OPTION_PERM_LATE)dit(bf(tt(perm-late=<mode>)))
1518 Sets the permissions of the fd to value <mode>
1519 [link(mode_t)(TYPE_MODE_T)] using the code(fchmod()) system call after
1520 opening or connecting the channel.
1521 This is useful only on file system entries.
1522 label(OPTION_APPEND)dit(bf(tt(append=<bool>)))
1523 Always writes data to the actual end of file.
1524 If the address is member of the OPEN option group,
1525 socat() uses the code(O_APPEND) flag with the code(open()) system call
1526 (link(example)(EXAMPLE_OPTION_APPEND)).
1527 Otherwise, socat() applies the code(fcntl(fd, F_SETFL, O_APPEND)) call.
1528 label(OPTION_NONBLOCK)dit(bf(tt(nonblock=<bool>)))
1529 Tries to open or use file in nonblocking mode. Its only effects are that the
1530 code(connect()) call of TCP addresses does not block, and that opening a
1531 named pipe for reading does not block.
1532 If the address is member of the OPEN option group,
1533 socat() uses the code(O_NONBLOCK) flag with the code(open()) system call.
1534 Otherwise, socat() applies the code(fcntl(fd, F_SETFL, O_NONBLOCK)) call.
1535 COMMENT(label(OPTION_NDELAY)dit(bf(tt(ndelay=<bool>)))
1536 Tries to open or use file in nonblocking mode. Has no effect because socat()
1537 works with code(select()).)
1538 COMMENT(label(OPTION_ASYNC)dit(bf(tt(async=<bool>)))
1539 Enables SIGIO for this fd. Has no effect, because socat() ignores SIGIO.)
1540 label(OPTION_O_BINARY)dit(bf(tt(binary)))
1541 Opens the file in binary mode to avoid implicit line terminator
1542 conversions (Cygwin).
1543 label(OPTION_O_TEXT)dit(bf(tt(text)))
1544 Opens the file in text mode to force implicit line terminator conversions
1545 (Cygwin).
1546 label(OPTION_O_NOINHERIT)dit(bf(tt(noinherit)))
1547 Does not keep this file open in a spawned process (Cygwin).
1548 label(OPTION_COOL_WRITE)dit(bf(tt(cool-write)))
1549 Takes it easy when write fails with EPIPE or ECONNRESET and logs the message
1550 with em(notice) level instead of em(error).
1551 This prevents the log file from being filled with useless error messages
1552 when socat() is used as a high volume server or proxy where clients often
1553 abort the connection.nl()
1554 This option is experimental.
1555 label(OPTION_END_CLOSE)dit(bf(tt(end-close)))
1556 Changes the (address dependent) method of ending a connection to just close
1557 the file descriptors. This is useful when the connection is to be reused by
1558 or shared with other processes (link(example)(EXAMPLE_END_CLOSE)).nl()
1559 Normally, socket connections will be ended with tt(shutdown(2)) which
1560 terminates the socket even if it is shared by multiple processes.
1561 tt(close(2)) "unlinks" the socket from the process but keeps it active as
1562 long as there are still links from other processes.nl()
1563 Similarly, when an address of type EXEC or SYSTEM is ended, socat() usually
1564 will explicitely kill the sub process. With this option, it will just close
1565 the file descriptors.
1566 label(OPTION_SHUT_NONE)dit(bf(tt(shut-none)))
1567 Changes the (address dependent) method of shutting down the write part of a
1568 connection to not do anything.
1569 label(OPTION_SHUT_DOWN)dit(bf(tt(shut-down)))
1570 Changes the (address dependent) method of shutting down the write part of a
1571 connection to tt(shutdown\(fd, SHUT_WR)). Is only useful with sockets.
1572 label(OPTION_SHUT_CLOSE)dit(bf(tt(shut-close)))
1573 Changes the (address dependent) method of shutting down the write part of a
1574 connection to tt(close\(fd)).
1575 label(OPTION_SHUT_NULL)dit(bf(tt(shut-null)))
1576 When one address indicates EOF, socat() will send a zero sized packet to the
1577 write channel of the other address to transfer the EOF condition. This is
1578 useful with UDP and other datagram protocols. Has been tested against
1579 netcat and socat with option link(null-eof)(OPTION_NULL_EOF).
1580 label(OPTION_NULL_EOF)dit(bf(tt(null-eof)))
1581 Normally socat() will ignore empty (zero size payload) packets arriving on
1582 datagram sockets, so it survives port scans. With this option socat()
1583 interprets empty datagram packets as EOF indicator (see
1584 link(shut-null)(OPTION_SHUT_NULL)).
1585 label(OPTION_IOCTL_VOID)dit(bf(tt(ioctl-void=<request>)))
1586 Calls tt(ioctl()) with the request value as second argument and NULL as
1587 third argument. This option allows to utilize ioctls that are not
1588 explicitely implemented in socat.
1589 label(OPTION_IOCTL_INT)dit(bf(tt(ioctl-int=<request>:<value>)))
1590 Calls tt(ioctl()) with the request value as second argument and the integer
1591 value as third argument.
1592 label(OPTION_IOCTL_INTP)dit(bf(tt(ioctl-intp=<request>:<value>)))
1593 Calls tt(ioctl()) with the request value as second argument and a pointer to
1594 the integer value as third argument.
1595 label(OPTION_IOCTL_BIN)dit(bf(tt(ioctl-bin=<request>:<value>)))
1596 Calls tt(ioctl()) with the request value as second argument and a pointer to
1597 the given data value as third argument. This data must be specified in
1598 link(<dalan>)(TYPE_DATA) form.
1599 label(OPTION_IOCTL_STRING)dit(bf(tt(ioctl-string=<request>:<value>)))
1600 Calls tt(ioctl()) with the request value as second argument and a pointer to
1601 the given string as third argument.
1602 link(<dalan>)(TYPE_DATA) form.
1603 enddit()
1604  
1605 startdit()enddit()nl()
1606  
1607  
1608 label(GROUP_NAMED)em(bf(NAMED option group))
1609  
1610 These options work on file system entries.nl()
1611 See also options link(user)(OPTION_USER), link(group)(OPTION_GROUP), and
1612 link(mode)(OPTION_MODE).
1613  
1614 startdit()
1615 label(OPTION_USER_EARLY)dit(bf(tt(user-early=<user>)))
1616 Changes the link(<user>)(TYPE_USER) (owner) of the file system entry before
1617 accessing it, using the
1618 code(chown()) system call. This call might require root privilege.
1619 label(OPTION_GROUP_EARLY)dit(bf(tt(group-early=<group>)))
1620 Changes the link(<group>)(TYPE_GROUP) of the file system entry before
1621 accessing it, using the
1622 code(chown()) system call. This call might require group membership or root
1623 privilege.
1624 label(OPTION_PERM_EARLY)dit(bf(tt(perm-early=<mode>)))
1625 Changes the <mode> [link(mode_t)(TYPE_MODE_T)] of the file system entry
1626 before accessing it, using the
1627 code(chmod()) system call. This call might require ownership or root
1628 privilege.
1629 label(OPTION_UMASK)dit(bf(tt(umask=<mode>)))
1630 Sets the umask of the process to <mode> [link(mode_t)(TYPE_MODE_T)] before
1631 accessing the file system entry (useful
1632 with unixdomain() sockets!). This call might affect all further operations
1633 of the socat() process!
1634 label(OPTION_UNLINK_EARLY)dit(bf(tt(unlink-early)))
1635 Unlinks (removes) the file before opening it and even before applying
1636 user-early etc.
1637 label(OPTION_UNLINK)dit(bf(tt(unlink)))
1638 Unlinks (removes) the file before accessing it, but after user-early etc.
1639 label(OPTION_UNLINK_LATE)dit(bf(tt(unlink-late)))
1640 Unlinks (removes) the file after opening it to make it inaccessible for
1641 other processes after a short race condition.
1642 label(OPTION_UNLINK_CLOSE)dit(bf(tt(unlink-close)))
1643 Removes the addresses file system entry when closing the address.
1644 For link(named pipes)(ADDRESS_NAMED_PIPE),
1645 link(listening unix domain sockets)(ADDRESS_UNIX_LISTEN),
1646 and the link(symbolic links)(OPTION_SYMBOLIC_LINK) of link(pty addresses)(ADDRESS_PTY),
1647 the default is 1; for link(created files)(ADDRESS_CREAT),
1648 link(opened files)(ADDRESS_OPEN),
1649 link(generic opened files)(ADDRESS_GOPEN), and
1650 link(client unix domain sockets)(ADDRESS_UNIX_CONNECT) the default is 0.
1651 enddit()
1652  
1653 startdit()enddit()nl()
1654  
1655  
1656 label(GROUP_OPEN)em(bf(OPEN option group))
1657  
1658 The OPEN group options allow to set flags with the code(open()) system call.
1659 E.g., option `creat' sets the code(O_CREAT) flag.nl()
1660 See also options link(append)(OPTION_APPEND) and
1661 link(nonblock)(OPTION_NONBLOCK).
1662 startdit()
1663 label(OPTION_O_CREAT)dit(bf(tt(creat=<bool>)))
1664 Creates the file if it does not exist (link(example)(EXAMPLE_OPTION_CREAT)).
1665 label(OPTION_DSYNC)dit(bf(tt(dsync=<bool>)))
1666 Blocks code(write()) calls until metainfo is physically written to media.
1667 label(OPTION_EXCL)dit(bf(tt(excl=<bool>)))
1668 With option creat, if file exists this is an error.
1669 label(OPTION_LARGEFILE)dit(bf(tt(largefile=<bool>)))
1670 On 32 bit systems, allows a file larger than 2^31 bytes.
1671 label(OPTION_O_NOATIME)dit(bf(tt(noatime)))
1672 Sets the O_NOATIME options, so reads do not change the access timestamp.
1673 label(OPTION_NOCTTY)dit(bf(tt(noctty=<bool>)))
1674 Does not make this file the controlling terminal.
1675 label(OPTION_NOFOLLOW)dit(bf(tt(nofollow=<bool>)))
1676 Does not follow symbolic links.
1677 label(OPTION_NSHARE)dit(bf(tt(nshare=<bool>)))
1678 Does not allow to share this file with other processes.
1679 label(OPTION_RSHARE)dit(bf(tt(rshare=<bool>)))
1680 Does not allow other processes to open this file for writing.
1681 label(OPTION_RSYNC)dit(bf(tt(rsync=<bool>)))
1682 Blocks code(write()) until metainfo is physically written to media.
1683 label(OPTION_SYNC)dit(bf(tt(sync=<bool>)))
1684 Blocks code(write()) until data is physically written to media.
1685 COMMENT(label(OPTION_DEFER)dit(bf(tt(defer=<bool>)))
1686 Temporarily stores write data in paging space.)
1687 COMMENT(label(OPTION_DELAY)dit(bf(tt(delay=<bool>)))
1688 Blocks code(open()) until share conditions are fulfilled.)
1689 COMMENT(label(OPTION_DIRECT)dit(bf(tt(direct=<bool>))))
1690 COMMENT(label(OPTION_DIRECTORY)dit(bf(tt(directory=<bool>)))
1691 Fails if file is not a directory. Not useful with socat().)
1692 label(OPTION_RDONLY)dit(bf(tt(rdonly=<bool>)))
1693 Opens the file for reading only.
1694 COMMENT(label(OPTION_RDWR)dit(bf(tt(rdwr=<bool>)))
1695 Opens the file for reading and writing.)
1696 label(OPTION_WRONLY)dit(bf(tt(wronly=<bool>)))
1697 Opens the file for writing only.
1698 label(OPTION_O_TRUNC)dit(bf(tt(trunc)))
1699 Truncates the file to size 0 during opening it.
1700 enddit()
1701  
1702  
1703 startdit()enddit()nl()
1704  
1705  
1706 label(GROUP_REG)em(bf(REG and BLK option group))
1707  
1708 These options are usually applied to a unix() file descriptor, but their
1709 semantics make sense only on a file supporting random access.
1710 startdit()
1711 label(OPTION_SEEK)dit(bf(tt(seek=<offset>)))
1712 Applies the code(lseek(fd, <offset>, SEEK_SET)) (or code(lseek64)) system
1713 call, thus positioning the file pointer absolutely to <offset>
1714 [link(off_t)(TYPE_OFF) or link(off64_t)(TYPE_OFF64)]. Please note that a
1715 missing value defaults to 1, not 0.
1716 label(OPTION_SEEK_CUR)dit(bf(tt(seek-cur=<offset>)))
1717 Applies the code(lseek(fd, <offset>, SEEK_CUR)) (or code(lseek64)) system
1718 call, thus positioning the file pointer <offset> [link(off_t)(TYPE_OFF) or
1719 link(off64_t)(TYPE_OFF64)] bytes relatively to its current position (which
1720 is usually 0). Please note that a missing value defaults to 1, not 0.
1721 label(OPTION_SEEK_END)dit(bf(tt(seek-end=<offset>)))
1722 Applies the code(lseek(fd, <offset>, SEEK_END)) (or code(lseek64)) system
1723 call, thus positioning the file pointer <offset> [link(off_t)(TYPE_OFF) or
1724 link(off64_t)(TYPE_OFF64)] bytes relatively to the files current end. Please
1725 note that a missing value defaults to 1, not 0.
1726 label(OPTION_FTRUNCATE)dit(bf(tt(ftruncate=<offset>)))
1727 Applies the code(ftruncate(fd, <offset>))
1728 (or code(ftruncate64) if available) system call, thus
1729 truncating the file at the position <offset> [link(off_t)(TYPE_OFF) or
1730 link(off64_t)(TYPE_OFF64)]. Please note that a missing value defaults to 1,
1731 not 0.
1732  
1733 label(OPTION_EXT2_SECRM_FL)dit(bf(tt(secrm=<bool>)))
1734 label(OPTION_EXT2_UNRM)dit(bf(tt(unrm=<bool>)))
1735 label(OPTION_EXT2_COMPR)dit(bf(tt(compr=<bool>)))
1736 label(OPTION_EXT2_SYNC)dit(bf(tt(ext2-sync=<bool>)))
1737 label(OPTION_EXT2_IMMUTABLE)dit(bf(tt(immutable=<bool>)))
1738 label(OPTION_EXT2_APPEND)dit(bf(tt(ext2-append=<bool>)))
1739 label(OPTION_EXT2_NODUMP)dit(bf(tt(nodump=<bool>)))
1740 label(OPTION_EXT2_NOATIME)dit(bf(tt(ext2-noatime=<bool>)))
1741 label(OPTION_EXT2_JOURNAL_DATA)dit(bf(tt(journal-data=<bool>)))
1742 label(OPTION_EXT2_NOTAIL)dit(bf(tt(notail=<bool>)))
1743 label(OPTION_EXT2_DIRSYNC)dit(bf(tt(dirsync=<bool>)))
1744 These options change non standard file attributes on operating systems and
1745 file systems that support these features, like Linux with ext2fs,
1746 ext3fs, or reiserfs. See man 1 chattr for information on these options.
1747 Please note that there might be a race condition between creating the file
1748 and applying these options.
1749 enddit()
1750  
1751 startdit()enddit()nl()
1752  
1753  
1754 label(GROUP_PROCESS)em(bf(PROCESS option group))
1755  
1756 Options of this group change the process properties instead of just affecting
1757 one data channel.
1758 For EXEC and SYSTEM addresses and for LISTEN and CONNECT type addresses with
1759 option FORK,
1760 these options apply to the child processes instead of the main socat() process.
1761 startdit()
1762 label(OPTION_CHROOT)dit(bf(tt(chroot=<directory>)))
1763 Performs a code(chroot()) operation to link(<directory>)(TYPE_DIRECTORY)
1764 after processing the address (link(example)(EXAMPLE_OPTION_CHROOT)). This call might require root privilege.
1765 label(OPTION_CHROOT_EARLY)dit(bf(tt(chroot-early=<directory>)))
1766 Performs a code(chroot()) operation to link(<directory>)(TYPE_DIRECTORY)
1767 before opening the address. This call might require root privilege.
1768 label(OPTION_SETGID)dit(bf(tt(setgid=<group>)))
1769 Changes the primary link(<group>)(TYPE_GROUP) of the process after
1770 processing the address. This call might require root privilege. Please note
1771 that this option does not drop other group related privileges.
1772 label(OPTION_SETGID_EARLY)dit(bf(tt(setgid-early=<group>)))
1773 Like link(setgit)(OPTION_SETGID) but is performed before opening the address.
1774 label(OPTION_SETUID)dit(bf(tt(setuid=<user>)))
1775 Changes the link(<user>)(TYPE_USER) (owner) of the process after processing
1776 the address. This call might require root privilege. Please note that this
1777 option does not drop group related privileges. Check if option
1778 link(su)(OPTION_SUBSTUSER) better fits your needs.
1779 label(OPTION_SETUID_EARLY)dit(bf(tt(setuid-early=<user>)))
1780 Like link(setuid)(OPTION_SETUID) but is performed before opening the
1781 address.
1782 label(OPTION_SUBSTUSER)dit(bf(tt(su=<user>)))
1783 Changes the link(<user>)(TYPE_USER) (owner) and groups of the process after
1784 processing the address (link(example)(EXAMPLE_OPTION_SUBSTUSER)). This call might require root privilege.
1785 label(OPTION_SUBSTUSER_DELAYED)dit(bf(tt(su-d=<user>)))
1786 Short name for bf(tt(substuser-delayed)).
1787 Changes the link(<user>)(TYPE_USER)
1788 (owner) and groups of the process after processing the address (link(example)(EXAMPLE_OPTION_SUBSTUSER_DELAYED)).
1789 The user and his groups are retrieved em(before) a possible
1790 code(chroot()). This call might require root privilege.
1791 label(OPTION_SETPGID)dit(bf(tt(setpgid=<pid_t>)))
1792 Makes the process a member of the specified process group
1793 link(<pid_t>)(TYPE_PID_T). If no value
1794 is given, or if the value is 0 or 1, the process becomes leader of a new
1795 process group.
1796 label(OPTION_SETSID)dit(bf(tt(setsid)))
1797 Makes the process the leader of a new session (link(example)(EXAMPLE_OPTION_SETSID)).
1798 enddit()
1799  
1800 startdit()enddit()nl()
1801  
1802  
1803 label(GROUP_READLINE)em(bf(READLINE option group))
1804  
1805 These options apply to the readline address type.
1806 startdit()
1807 label(OPTION_HISTORY)dit(bf(tt(history=<filename>)))
1808 Reads and writes history from/to link(<filename>)(TYPE_FILENAME) (link(example)(EXAMPLE_OPTION_HISTORY)).
1809 label(OPTION_NOPROMPT)dit(bf(tt(noprompt)))
1810 Since version 1.4.0, socat() per default tries to determine a prompt -
1811 that is then passed to the readline call - by remembering the last
1812 incomplete line of the output. With this option, socat() does not pass a
1813 prompt to readline, so it begins line editing in the first column
1814 of the terminal.
1815 label(OPTION_NOECHO)dit(bf(tt(noecho=<pattern>)))
1816 Specifies a regular pattern for a prompt that prevents the following input
1817 line from being displayed on the screen and from being added to the history.
1818 The prompt is defined as the text that was output to the readline address
1819 after the lastest newline character and before an input character was
1820 typed. The pattern is a regular expression, e.g.
1821 "^[Pp]assword:.*$" or "([Uu]ser:|[Pp]assword:)". See regex\(7) for details.
1822 (link(example)(EXAMPLE_OPTION_NOECHO))
1823 label(OPTION_PROMPT)dit(bf(tt(prompt=<string>)))
1824 Passes the string as prompt to the readline function. readline prints this
1825 prompt when stepping through the history. If this string matches a constant
1826 prompt issued by an interactive program on the other socat() address,
1827 consistent look and feel can be archieved.
1828 enddit()
1829  
1830 startdit()enddit()nl()
1831  
1832  
1833 label(GROUP_APPLICATION)em(bf(APPLICATION option group))
1834  
1835 This group contains options that work at data level.
1836 Note that these options only apply to the "raw" data transferred by socat,
1837 but not to protocol data used by addresses like
1838 link(PROXY)(ADDRESS_PROXY_CONNECT).
1839 startdit()
1840 label(OPTION_CR)dit(bf(tt(cr)))
1841 Converts the default line termination character NL ('\n', 0x0a) to/from CR
1842 ('\r', 0x0d) when writing/reading on this channel.
1843 label(OPTION_CRNL)dit(bf(tt(crnl)))
1844 Converts the default line termination character NL ('\n', 0x0a) to/from CRNL
1845 ("\r\n", 0x0d0a) when writing/reading on this channel (link(example)(EXAMPLE_OPTION_CRNL)).
1846 Note: socat() simply strips all CR characters.
1847 label(OPTION_IGNOREEOF)dit(bf(tt(ignoreeof)))
1848 When EOF occurs on this channel, socat() ignores it and tries to read more
1849 data (like "tail -f") (link(example)(EXAMPLE_OPTION_IGNOREEOF)).
1850 label(OPTION_READBYTES)dit(bf(tt(readbytes=<bytes>)))
1851 socat() reads only so many bytes from this address (the address provides
1852 only so many bytes for transfer and pretends to be at EOF afterwards).
1853 Must be greater than 0.
1854 label(OPTION_LOCKFILE)dit(bf(tt(lockfile=<filename>)))
1855 If lockfile exists, exits with error. If lockfile does not exist, creates it
1856 and continues, unlinks lockfile on exit.
1857 label(OPTION_WAITLOCK)dit(bf(tt(waitlock=<filename>)))
1858 If lockfile exists, waits until it disappears. When lockfile does not exist,
1859 creates it and continues, unlinks lockfile on exit.
1860 label(OPTION_ESCAPE)dit(bf(tt(escape=<int>)))
1861 Specifies the numeric code of a character that triggers EOF on the input
1862 stream. It is useful with a terminal in raw mode
1863 (link(example)(EXAMPLE_OPTION_ESCAPE)).
1864 enddit()
1865  
1866 startdit()enddit()nl()
1867  
1868  
1869 label(GROUP_SOCKET)em(bf(SOCKET option group))
1870  
1871 These options are intended for all kinds of sockets, e.g. IP or unixdomain(). Most are applied with a code(setsockopt()) call.
1872 startdit()
1873 label(OPTION_BIND)dit(bf(tt(bind=<sockname>)))
1874 Binds the socket to the given socket address using the code(bind()) system
1875 call. The form of <sockname> is socket domain dependent:
1876 IP4 and IP6 allow the form [hostname|hostaddress][:(service|port)] (link(example)(EXAMPLE_OPTION_BIND_TCP4)),
1877 unixdomain() sockets require link(<filename>)(TYPE_FILENAME).
1878 label(OPTION_CONNECT_TIMEOUT)dit(bf(tt(connect-timeout=<seconds>)))
1879 Abort the connection attempt after <seconds> [link(timeval)(TYPE_TIMEVAL)]
1880 with error status.
1881 label(OPTION_SO_BINDTODEVICE)dit(bf(tt(so-bindtodev=<interface>)))
1882 Binds the socket to the given link(<interface>)(TYPE_INTERFACE).
1883 This option might require root privilege.
1884 label(OPTION_SO_BROADCAST)dit(bf(tt(broadcast)))
1885 For datagram sockets, allows sending to broadcast addresses and receiving
1886 packets addressed to broadcast addresses.
1887 COMMENT(label(OPTION_BSDCOMPAT)dit(bf(tt(bsdcompat)))
1888 Emulates some (old?) bugs of the BSD socket implementation.)
1889 label(OPTION_DEBUG)dit(bf(tt(debug)))
1890 Enables socket debugging.
1891 label(OPTION_DONTROUTE)dit(bf(tt(dontroute)))
1892 Only communicates with directly connected peers, does not use routers.
1893 label(OPTION_KEEPALIVE)dit(bf(tt(keepalive)))
1894 Enables sending keepalives on the socket.
1895 label(OPTION_LINGER)dit(bf(tt(linger=<seconds>)))
1896 Blocks code(shutdown()) or code(close()) until data transfers have finished
1897 or the given timeout [link(int)(TYPE_INT)] expired.
1898 COMMENT(label(OPTION_NOREUSEADDR)dit(bf(tt(noreuseaddr)))
1899 Set the code(SO_NOREUSEADDR) socket option.)
1900 label(OPTION_OOBINLINE)dit(bf(tt(oobinline)))
1901 Places out-of-band data in the input data stream.
1902 label(OPTION_PRIORITY)dit(bf(tt(priority=<priority>)))
1903 Sets the protocol defined <priority> [link(<int>)(TYPE_INT)] for outgoing
1904 packets.
1905 label(OPTION_RCVBUF)dit(bf(tt(rcvbuf=<bytes>)))
1906 Sets the size of the receive buffer after the code(socket()) call to
1907 <bytes> [link(int)(TYPE_INT)]. With TCP
1908 sockets, this value corresponds to the socket's maximal window size.
1909 label(OPTION_RCVBUF_LATE)dit(bf(tt(rcvbuf-late=<bytes>)))
1910 Sets the size of the receive buffer when the socket is already
1911 connected to <bytes> [link(int)(TYPE_INT)].
1912 With TCP sockets, this value corresponds to the socket's
1913 maximal window size.
1914 label(OPTION_RCVLOWAT)dit(bf(tt(rcvlowat=<bytes>)))
1915 Specifies the minimum number of received bytes [link(int)(TYPE_INT)] until
1916 the socket layer will pass the buffered data to socat().
1917 label(OPTION_RCVTIMEO)dit(bf(tt(rcvtimeo=<seconds>)))
1918 Sets the receive timeout [link(timeval)(TYPE_TIMEVAL)].
1919 label(OPTION_REUSEADDR)dit(bf(tt(reuseaddr)))
1920 Allows other sockets to bind to an address even if parts of it (e.g. the
1921 local port) are already in use by socat() (link(example)(EXAMPLE_OPTION_REUSEADDR)).
1922 label(OPTION_SNDBUF)dit(bf(tt(sndbuf=<bytes>)))
1923 Sets the size of the send buffer after the code(socket()) call to
1924 <bytes> [link(int)(TYPE_INT)].
1925 label(OPTION_SNDBUF_LATE)dit(bf(tt(sndbuf-late=<bytes>)))
1926 Sets the size of the send buffer when the socket is connected to
1927 <bytes> [link(int)(TYPE_INT)].
1928 label(OPTION_SNDLOWAT)dit(bf(tt(sndlowat=<bytes>)))
1929 Specifies the minimum number of bytes in the send buffer until the socket
1930 layer will send the data to <bytes> [link(int)(TYPE_INT)].
1931 label(OPTION_SNDTIMEO)dit(bf(tt(sndtimeo=<seconds>)))
1932 Sets the send timeout to seconds [link(timeval)(TYPE_TIMEVAL)].
1933 label(OPTION_PROTOCOL_FAMILY)dit(bf(tt(pf=<string>)))
1934 Forces the use of the specified IP version or protocol. <string> can be
1935 something like "ip4" or "ip6". The resulting value is
1936 used as first argument to the code(socket()) or code(socketpair()) calls.
1937 This option affects address resolution and the required syntax of bind and
1938 range options.
1939 label(OPTION_SO_TYPE)dit(bf(tt(type=<type>)))
1940 Sets the type of the socket, specified as second argument to the
1941 code(socket()) or code(socketpair()) calls, to <type>
1942 [link(int)(TYPE_INT)]. Address resolution is not affected by this option.
1943 Under Linux, 1 means stream oriented socket, 2 means datagram socket, and 3
1944 means raw socket.
1945 label(OPTION_SO_PROTOTYPE)dit(bf(tt(prototype)))
1946 Sets the protocol of the socket, specified as third argument to the
1947 code(socket()) or code(socketpair()) calls, to <prototype>
1948 [link(int)(TYPE_INT)]. Address resolution is not affected by this option.
1949 6 means TCP, 17 means UDP.
1950 COMMENT(label(OPTION_USELOOPBACK)dit(bf(tt(useloopback)))
1951 Sets the code(SO_USELOOPBACK) socket option.)
1952 COMMENT(label(OPTION_ACCEPTCONN)dit(bf(tt(acceptconn)))
1953 Tries to set the code(SO_ACCEPTCONN) socket option.)
1954 COMMENT(label(OPTION_ATTACHFILTER)dit(bf(tt(attachfilter)))
1955 Tries to set the code(SO_ATTACH_FILTER) socket option.)
1956 COMMENT(label(OPTION_AUDIT)dit(bf(tt(audit)))
1957 Sets the code(SO_AUDIT) socket option.)
1958 COMMENT(label(OPTION_CHSUMRECV)dit(bf(tt(cksumrecv)))
1959 Sets the code(SO_CKSUMRECV) socket option.)
1960 COMMENT(label(OPTION_DETACHFILTER)dit(bf(tt(detachfilter)))
1961 Tries to set the code(SO_DETACH_FILTER) socket option.)
1962 COMMENT(label(OPTION_DGRAMERRIND)dit(bf(tt(dgramerrind)))
1963 Sets the code(SO_DGRAM_ERRIND) socket option.)
1964 COMMENT(label(OPTION_DONTLINGER)dit(bf(tt(dontlinger)))
1965 Sets the code(SO_DONTLINGER) socket option.)
1966 COMMENT(label(OPTION_ERROR)dit(bf(tt(error)))
1967 Tries to set this read only socket option.)
1968 COMMENT(label(OPTION_FIOSETOWN)dit(bf(tt(fiosetown=<pid_t>)))
1969 Sets the receiver of SIGIO.)
1970 COMMENT(label(OPTION_KERNACCEPT)dit(bf(tt(kernaccept)))
1971 Sets the code(SO_KERNACCEPT) socket option.)
1972 COMMENT(label(OPTION_NOCHECK)dit(bf(tt(nocheck)))
1973 Sets the code(SO_NO_CHECK) socket option. Undocumented...)
1974 COMMENT(label(OPTION_PASSCRED)dit(bf(tt(passcred)))
1975 Set the code(SO_PASSCRED) socket option.)
1976 COMMENT(label(OPTION_PEERCRED)dit(bf(tt(peercred)))
1977 This is a read-only socket option.)
1978 COMMENT(label(OPTION_REUSEPORT)dit(bf(tt(reuseport)))
1979 Set the code(SO_REUSEPORT) socket option.)
1980 COMMENT(label(OPTION_SECUTIYAUTHENTICATION)dit(bf(tt(securityauthentication)))
1981 Set the code(SO_SECURITY_AUTHENTICATION) socket option.)
1982 COMMENT(label(OPTION_SECURITYENCRYPTIONNETWORK)dit(bf(tt(securityencryptionnetwork)))
1983 Set the code(SO_SECURITY_ENCRYPTION_NETWORK) socket option.)
1984 COMMENT(label(OPTION_SECURITYENCRYPTIONTRANSPORT)dit(bf(tt(securityencryptiontransport)))
1985 Set the code(SO_SECURITY_ENCRYPTION_TRANSPORT) socket option.)
1986 COMMENT(label(OPTION_SIOCSPGRP)dit(bf(tt(siocspgrp=<pid_t>)))
1987 Set the SIOCSPGRP with code(ioclt()) to enable SIGIO.)
1988 COMMENT(label(OPTION_USEIFBUFS)dit(bf(tt(useifbufs)))
1989 Set the code(SO_USE_IFBUFS) socket option.)
1990 label(OPTION_SO_TIMESTAMP)dit(bf(tt(so-timestamp)))
1991 Sets the SO_TIMESTAMP socket option. This enables receiving and logging of
1992 timestamp ancillary messages.
1993 label(OPTION_SETSOCKOPT_INT)dit(bf(tt(setsockopt-int=<level>:<optname>:<optval>)))
1994 Invokes tt(setsockopt()) for the socket with the given parameters. tt(level)
1995 [link(int)(TYPE_INT)] is used as second argument to tt(setsockopt()) and
1996 specifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or SOL_SOCKET for
1997 the socket layer (1 on Linux). tt(optname) [link(int)(TYPE_INT)] is the
1998 third argument to tt(setsockopt()) and tells which socket option is to be
1999 set. For the actual numbers you might have to look up the appropriate include
2000 files of your system. The 4th tt(setsockopt()) parameter, tt(value)
2001 [link(int)(TYPE_INT)], is passed to the function per pointer, and for the
2002 length parameter sizeof\(int) is taken implicitely.
2003 label(OPTION_SETSOCKOPT_BIN)dit(bf(tt(setsockopt-bin=<level>:<optname>:<optval>)))
2004 Like tt(setsockopt-int), but <optval> must be provided in
2005 link(dalan)(TYPE_DATA) format and specifies an arbitrary sequence of bytes;
2006 the length parameter is automatically derived from the data.
2007 label(OPTION_SETSOCKOPT_STRING)dit(bf(tt(setsockopt-string=<level>:<optname>:<optval>)))
2008 Like tt(setsockopt-int), but <optval> must be a link(string)(TYPE_STRING).
2009 This string is passed to the function with trailing null character, and the
2010 length parameter is automatically derived from the data.
2011 enddit()
2012  
2013 startdit()enddit()nl()
2014  
2015  
2016 label(GROUP_SOCK_UNIX)em(bf(UNIX option group))
2017  
2018 These options apply to UNIX domain based addresses.
2019 startdit()
2020 label(OPTION_UNIX_TIGHTSOCKLEN)dit(bf(tt(unix-tightsocklen=[0|1])))
2021 On socket operations, pass a socket address length that does not include the
2022 whole code(struct sockaddr_un) record but (besides other components) only
2023 the relevant part of the filename or abstract string. Default is 1.
2024 enddit()
2025  
2026 label(GROUP_IP4)
2027 label(GROUP_IP)em(bf(IP4 and IP6 option groups))
2028  
2029 These options can be used with IPv4 and IPv6 based sockets.
2030 startdit()
2031 label(OPTION_TOS)dit(bf(tt(tos=<tos>)))
2032 Sets the TOS (type of service) field of outgoing packets to <tos>
2033 [link(byte)(TYPE_BYTE)] (see RFC 791).
2034 label(OPTION_TTL)dit(bf(tt(ttl=<ttl>)))
2035 Sets the TTL (time to live) field of outgoing packets to <ttl>
2036 [link(byte)(TYPE_BYTE)].
2037 label(OPTION_IPOPTIONS)dit(bf(tt(ip-options=<data>)))
2038 Sets IP options like source routing. Must be given in binary form,
2039 recommended format is a leading "x" followed by an even number of hex
2040 digits. This option may be used multiple times, data are appended.
2041 E.g., to connect to host 10.0.0.1 via some gateway using a loose source
2042 route, use the gateway as address parameter and set a loose source route
2043 using the option code(ip-options=x8307040a000001).nl()
2044 IP options are defined in RFC 791. COMMENT(, RFC 2113)nl()
2045 COMMENT( x00 end of option list
2046 x01 no operation (nop)
2047 x0211 security
2048 x03 loose source route
2049 x09 strict source route
2050 x07 record route
2051 x0804 stream ID
2052 x44 internet timestamp)
2053 label(OPTION_MTUDISCOVER)dit(bf(tt(mtudiscover=<0|1|2>)))
2054 Takes 0, 1, 2 to never, want, or always use path MTU discover on this
2055 socket.
2056 COMMENT(label(OPTION_HRDINCL)dit(bf(tt(ip-hdrincl)))
2057 Tell the raw socket that the application data includes the IP header.)
2058 COMMENT(label(OPTION_IP_MULTICAST_LOOP)dit(bf(tt(ip-multicastloop)))
2059 Allow looping back outgoing multicast to the local interface.)
2060 COMMENT(label(OPTION_IP_MULTICAST_TTL)dit(bf(tt(ip-multicastttl)))
2061 Set the TTL for outgoing multicast packets.)
2062 label(OPTION_IP_PKTINFO)dit(bf(tt(ip-pktinfo)))
2063 Sets the IP_PKTINFO socket option. This enables receiving and logging of
2064 ancillary messages containing destination address and interface (Linux)
2065 (link(example)(EXAMPLE_ANCILLARY)).
2066 COMMENT(label(OPTION_PKTOPTS)dit(bf(tt(ip-pktopts)))
2067 Set the IP_PKTOPTIONS socket option.)
2068 label(OPTION_IP_RECVERR)dit(bf(tt(ip-recverr)))
2069 Sets the IP_RECVERR socket option. This enables receiving and logging of
2070 ancillary messages containing detailled error information.
2071 label(OPTION_IP_RECVOPTS)dit(bf(tt(ip-recvopts)))
2072 Sets the IP_RECVOPTS socket option. This enables receiving and logging of IP
2073 options ancillary messages (Linux, *BSD).
2074 label(OPTION_IP_RECVTOS)dit(bf(tt(ip-recvtos)))
2075 Sets the IP_RECVTOS socket option. This enables receiving and logging of TOS
2076 (type of service) ancillary messages (Linux).
2077 label(OPTION_IP_RECVTTL)dit(bf(tt(ip-recvttl)))
2078 Sets the IP_RECVTTL socket option. This enables receiving and logging of TTL
2079 (time to live) ancillary messages (Linux, *BSD).
2080 COMMENT(label(OPTION_RETOPTS)dit(bf(tt(ip-retopts)))
2081 Set the IP_RETOPTS socket option.)
2082 label(OPTION_IP_RECVDSTADDR)dit(bf(tt(ip-recvdstaddr)))
2083 Sets the IP_RECVDSTADDR socket option. This enables receiving and logging of
2084 ancillary messages containing destination address (*BSD)
2085 (link(example)(EXAMPLE_ANCILLARY)).
2086 label(OPTION_IP_RECVIF)dit(bf(tt(ip-recvif)))
2087 Sets the IP_RECVIF socket option. This enables receiving and logging of
2088 interface ancillary messages (*BSD) (link(example)(EXAMPLE_ANCILLARY)).
2089 COMMENT(label(OPTION_ROUTERALERT)dit(bf(tt(routeralert)))
2090 Set the IP_ROUTER_ALERT socket option.)
2091 label(OPTION_IP_ADD_MEMBERSHIP)
2092 dit(bf(tt(ip-add-membership=<multicast-address:interface-address>)))
2093 dit(bf(tt(ip-add-membership=<multicast-address:interface-name>)))
2094 dit(bf(tt(ip-add-membership=<multicast-address:interface-index>)))
2095 dit(bf(tt(ip-add-membership=<multicast-address:interface-address:interface-name>)))
2096 dit(bf(tt(ip-add-membership=<multicast-address:interface-address:interface-index>)))
2097 Makes the socket member of the specified multicast group. This is currently
2098 only implemented for IPv4. The option takes the IP address of the multicast
2099 group and info about the desired network interface. The most common syntax
2100 is the first one, while the others are only available on systems that
2101 provide tt(struct mreqn) (Linux).nl()
2102 The indices of active network interfaces can be shown using the utility
2103 procan().
2104 label(OPTION_IP_MULTICAST_IF)
2105 dit(bf(tt(ip-multicast-if=<hostname>)))
2106 Specifies hostname or address of the network interface to be used for
2107 multicast traffic.
2108 label(OPTION_IP_MULTICAST_LOOP)
2109 dit(bf(tt(ip-multicast-loop=<bool>)))
2110 Specifies if outgoing multicast traffic should loop back to the interface.
2111 label(OPTION_IP_MULTICAST_TTL)
2112 dit(bf(tt(ip-multicast-ttl=<byte>)))
2113 Sets the TTL used for outgoing multicast traffic. Default is 1.
2114 label(OPTION_RES_DEBUG)dit(bf(tt(res-debug)))
2115 label(OPTION_RES_AAONLY)dit(bf(tt(res-aaonly)))
2116 label(OPTION_RES_USEVC)dit(bf(tt(res-usevc)))
2117 label(OPTION_RES_PRIMARY)dit(bf(tt(res-primary)))
2118 label(OPTION_RES_IGNTC)dit(bf(tt(res-igntc)))
2119 label(OPTION_RES_RECURSE)dit(bf(tt(res-recurse)))
2120 label(OPTION_RES_DEFNAMES)dit(bf(tt(res-defnames)))
2121 label(OPTION_RES_STAYOPEN)dit(bf(tt(res-stayopen)))
2122 label(OPTION_RES_DNSRCH)dit(bf(tt(res-dnsrch)))
2123 These options set the corresponding resolver (name resolution) option flags.
2124 Append "=0" to clear a default option. See man resolver\(5) for more
2125 information on these options. Note: these options are valid only for the
2126 address they are applied to.
2127  
2128 enddit()
2129  
2130 startdit()enddit()nl()
2131  
2132  
2133 label(GROUP_IP6)em(bf(IP6 option group))
2134  
2135 These options can only be used on IPv6 based sockets. See link\(IP
2136 options)(GROUP_IP) for options that can be applied to both IPv4 and IPv6
2137 sockets.
2138 startdit()
2139 label(OPTION_IPV6_V6ONLY)dit(bf(tt(ipv6only=<bool>)))
2140 Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will also accept
2141 connections using IPv4 protocol on the same port. The default is system
2142 dependent.
2143 label(OPTION_IPV6_RECVDSTOPTS)dit(bf(tt(ipv6-recvdstopts)))
2144 Sets the IPV6_RECVDSTOPTS socket option. This enables receiving and logging
2145 of ancillary messages containing the destination options.
2146 label(OPTION_IPV6_RECVHOPLIMIT)dit(bf(tt(ipv6-recvhoplimit)))
2147 Sets the IPV6_RECVHOPLIMIT socket option. This enables receiving and logging
2148 of ancillary messages containing the hoplimit.
2149 label(OPTION_IPV6_RECVHOPOPTS)dit(bf(tt(ipv6-recvhopopts)))
2150 Sets the IPV6_RECVHOPOPTS socket option. This enables receiving and logging
2151 of ancillary messages containing the hop options.
2152 label(OPTION_IPV6_RECVPKTINFO)dit(bf(tt(ipv6-recvpktinfo)))
2153 Sets the IPV6_RECVPKTINFO socket option. This enables receiving and logging
2154 of ancillary messages containing destination address and interface.
2155 label(OPTION_IPV6_UNICAST_HOPS)dit(bf(tt(ipv6-unicast-hops=link(TYPE_INT)(<int>))))
2156 Sets the IPV6_UNICAST_HOPS socket option. This sets the hop count limit
2157 (TTL) for outgoing unicast packets.
2158 label(OPTION_IPV6_RECVRTHDR)dit(bf(tt(ipv6-recvrthdr)))
2159 Sets the IPV6_RECVRTHDR socket option. This enables receiving and logging
2160 of ancillary messages containing routing information.
2161 label(OPTION_IPV6_TCLASS)dit(bf(tt(ipv6-tclass)))
2162 Sets the IPV6_TCLASS socket option. This sets the transfer class of outgoing
2163 packets.
2164 label(OPTION_IPV6_RECVTCLASS)dit(bf(tt(ipv6-recvtclass)))
2165 Sets the IPV6_RECVTCLASS socket option. This enables receiving and logging
2166 of ancillary messages containing the transfer class.
2167 enddit()
2168  
2169 startdit()enddit()nl()
2170  
2171  
2172 label(GROUP_TCP)em(bf(TCP option group))
2173  
2174 These options may be applied to TCP sockets. They work by invoking code(setsockopt()) with the appropriate parameters.
2175 startdit()
2176 label(OPTION_CORK)dit(bf(tt(cork)))
2177 Doesn't send packets smaller than MSS (maximal segment size).
2178 label(OPTION_DEFER-ACCEPT)dit(bf(tt(defer-accept)))
2179 While listening, accepts connections only when data from the peer arrived.
2180 label(OPTION_KEEPCNT)dit(bf(tt(keepcnt=<count>)))
2181 Sets the number of keepalives before shutting down the socket to
2182 <count> [link(int)(TYPE_INT)].
2183 label(OPTION_KEEPIDLE)dit(bf(tt(keepidle=<seconds>)))
2184 Sets the idle time before sending the first keepalive to <seconds>
2185 [link(int)(TYPE_INT)].
2186 label(OPTION_KEEPINTVL)dit(bf(tt(keepintvl=<seconds>)))
2187 Sets the interval between two keepalives to <seconds>
2188 [link(int)(TYPE_INT)].
2189 label(OPTION_LINGER2)dit(bf(tt(linger2=<seconds>)))
2190 Sets the time to keep the socket in FIN-WAIT-2 state to <seconds>
2191 [link(int)(TYPE_INT)].
2192 label(OPTION_MSS)dit(bf(tt(mss=<bytes>)))
2193 Sets the MSS (maximum segment size) after the code(socket()) call to <bytes>
2194 [link(int)(TYPE_INT)]. This
2195 value is then proposed to the peer with the SYN or SYN/ACK packet
2196 (link(example)(EXAMPLE_OPTION_MSS)).
2197 label(OPTION_MSS_LATE)dit(bf(tt(mss-late=<bytes>)))
2198 Sets the MSS of the socket after connection has been established to <bytes>
2199 [link(int)(TYPE_INT)].
2200 label(OPTION_NODELAY)dit(bf(tt(nodelay)))
2201 Turns off the Nagle algorithm for measuring the RTT (round trip time).
2202 label(OPTION_RFC1323)dit(bf(tt(rfc1323)))
2203 Enables RFC1323 TCP options: TCP window scale, round-trip time measurement
2204 (RTTM), and protect against wrapped sequence numbers (PAWS) (AIX).
2205 label(OPTION_STDURG)dit(bf(tt(stdurg)))
2206 Enables RFC1122 compliant urgent pointer handling (AIX).
2207 label(OPTION_SYNCNT)dit(bf(tt(syncnt=<count>)))
2208 Sets the maximal number of SYN retransmits during connect to <count>
2209 [link(int)(TYPE_INT)].
2210 COMMENT(label(OPTION_INFO)dit(bf(tt(info)))
2211 Tries to set the read-only TCP_INFO socket option.)
2212 COMMENT(label(OPTION_WINDOW_CLAMP)dit(bf(tt(window-clamp)))
2213 Sets the TCP_WINDOW_CLAMP socket option.)
2214 label(OPTION_TCP_MD5SIG)dit(bf(tt(md5sig)))
2215 Enables generation of MD5 digests on the packets (FreeBSD).
2216 label(OPTION_TCP_NOOPT)dit(bf(tt(noopt)))
2217 Disables use of TCP options (FreeBSD, MacOSX).
2218 label(OPTION_TCP_NOPUSH)dit(bf(tt(nopush)))
2219 sets the TCP_NOPUSH socket option (FreeBSD, MacOSX).
2220 label(OPTION_TCP_SACK_DISABLE)dit(bf(tt(sack-disable)))
2221 Disables use the selective acknowledge feature (OpenBSD).
2222 label(OPTION_TCP_SIGNATURE_ENABLE)dit(bf(tt(signature-enable)))
2223 Enables generation of MD5 digests on the packets (OpenBSD).
2224 label(OPTION_TCP_ABORT_THRESHOLD)dit(bf(tt(abort-threshold=<milliseconds>)))
2225 Sets the time to wait for an answer of the peer on an established connection
2226 (HP-UX).
2227 label(OPTION_TCP_CONN_ABORT_THRESHOLD)dit(bf(tt(conn-abort-threshold=<milliseconds>)))
2228 Sets the time to wait for an answer of the server during the initial connect
2229 (HP-UX).
2230 label(OPTION_TCP_KEEPINIT)dit(bf(tt(keepinit)))
2231 Sets the time to wait for an answer of the server during connect\() before
2232 giving up. Value in half seconds, default is 150 (75s) (Tru64).
2233 label(OPTION_TCP_PAWS)dit(bf(tt(paws)))
2234 Enables the "protect against wrapped sequence numbers" feature (Tru64).
2235 label(OPTION_TCP_SACKENA)dit(bf(tt(sackena)))
2236 Enables selective acknowledge (Tru64).
2237 label(OPTION_TCP_TSOPTENA)dit(bf(tt(tsoptena)))
2238 Enables the time stamp option that allows RTT recalculation on existing
2239 connections (Tru64).
2240 enddit()
2241  
2242 startdit()enddit()nl()
2243  
2244  
2245 label(GROUP_SCTP)em(bf(SCTP option group))
2246  
2247 These options may be applied to SCTP stream sockets.
2248 startdit()
2249 label(OPTION_SCTP_NODELAY)dit(bf(tt(sctp-nodelay)))
2250 Sets the SCTP_NODELAY socket option that disables the Nagle algorithm.
2251 label(OPTION_SCTP_MAXSEG)dit(bf(tt(sctp-maxseg=<bytes>)))
2252 Sets the SCTP_MAXSEG socket option to <bytes> [link(int)(TYPE_INT)]. This
2253 value is then proposed to the peer with the SYN or SYN/ACK packet.
2254 enddit()
2255  
2256 startdit()enddit()nl()
2257  
2258  
2259 em(bf(UDP, TCP, and SCTP option groups))
2260  
2261 Here we find options that are related to the network port mechanism and thus
2262 can be used with UDP, TCP, and SCTP client and server addresses.
2263 startdit()
2264 label(OPTION_SOURCEPORT)dit(bf(tt(sourceport=<port>)))
2265 For outgoing (client) TCP and UDP connections, it sets the source
2266 link(<port>)(TYPE_PORT) using an extra code(bind()) call.
2267 With TCP or UDP listen addresses, socat() immediately shuts down the
2268 connection if the client does not use this sourceport (link(example)(EXAMPLE_OPTION_SOURCEPORT)).
2269 label(OPTION_LOWPORT)dit(bf(tt(lowport)))
2270 Outgoing (client) TCP and UDP connections with this option use
2271 an unused random source port between 640 and 1023 incl. On UNIX class operating
2272 systems, this requires root privilege, and thus indicates that the
2273 client process is authorized by local root.
2274 TCP and UDP listen addresses with this option immediately shut down the
2275 connection if the client does not use a sourceport <= 1023.
2276 This mechanism can provide limited authorization under some circumstances.
2277 enddit()
2278  
2279 startdit()enddit()nl()
2280  
2281  
2282 label(GROUP_SOCKS)em(bf(SOCKS option group))
2283  
2284 When using SOCKS type addresses, some socks specific options can be set.
2285 startdit()
2286 label(OPTION_SOCKSPORT)dit(bf(tt(socksport=<tcp service>)))
2287 Overrides the default "socks" service or port 1080 for the socks server
2288 port with link(<TCP service>)(TYPE_TCP_SERVICE).
2289 label(OPTION_SOCKSUSER)dit(bf(tt(socksuser=<user>)))
2290 Sends the <user> [link(string)(TYPE_STRING)] in the username field to the
2291 socks server. Default is the actual user name ($LOGNAME or $USER) (link(example)(EXAMPLE_OPTION_SOCKSUSER)).
2292 enddit()
2293  
2294 startdit()enddit()nl()
2295  
2296  
2297 label(GROUP_HTTP)em(bf(HTTP option group))
2298  
2299 Options that can be provided with HTTP type addresses. The only HTTP address
2300 currently implemented is link(proxy-connect)(ADDRESS_PROXY_CONNECT).
2301  
2302 startdit()
2303 label(OPTION_PROXYPORT)dit(bf(tt(proxyport=<TCP service>)))
2304 Overrides the default HTTP proxy port 8080 with
2305 link(<TCP service>)(TYPE_TCP_SERVICE).
2306 label(OPTION_IGNORECR)dit(bf(tt(ignorecr)))
2307 The HTTP protocol requires the use of CR+NL as line terminator. When a proxy
2308 server violates this standard, socat() might not understand its answer.
2309 This option directs socat() to interprete NL as line terminator and
2310 to ignore CR in the answer. Nevertheless, socat() sends CR+NL to the proxy.
2311 label(OPTION_PROXY_AUTHORIZATION)dit(bf(tt(proxyauth=<username>:<password>)))
2312 Provide "basic" authentication to the proxy server. The argument to the
2313 option is used with a "Proxy-Authorization: Base" header in base64 encoded
2314 form.nl()
2315 Note: username and password are visible for every user on the local machine
2316 in the process list; username and password are transferred to the proxy
2317 server unencrypted (base64 encoded) and might be sniffed.
2318 label(OPTION_PROXY_RESOLVE)dit(bf(tt(resolve)))
2319 Per default, socat() sends to the proxy a CONNECT request containing the
2320 target hostname. With this option, socat() resolves the hostname locally and
2321 sends the IP address. Please note that, according to RFC 2396, only name
2322 resolution to IPv4 addresses is implemented.
2323 enddit()
2324  
2325 startdit()enddit()nl()
2326  
2327  
2328 label(GROUP_RANGE)em(bf(RANGE option group))
2329  
2330 These options check if a connecting client should be granted access. They can
2331 be applied to listening and receiving network sockets. tcp-wrappers options
2332 fall into this group.
2333 startdit()
2334 label(OPTION_RANGE)dit(bf(tt(range=<address-range>)))
2335 After accepting a connection, tests if the peer is within em(range). For
2336 IPv4 addresses, address-range takes the form address/bits, e.g.
2337 10.0.0.0/8, or address:mask, e.g. 10.0.0.0:255.0.0.0 (link(example)(EXAMPLE_OPTION_RANGE)); for IPv6, it is [ip6-address/bits], e.g. [::1/128].
2338 If the client address does not match, socat() issues a warning and keeps
2339 listening/receiving.
2340 label(OPTION_TCPWRAPPERS)dit(bf(tt(tcpwrap[=<name>])))
2341 Uses Wietse Venema's libwrap (tcpd) library to determine
2342 if the client is allowed to connect. The configuration files are
2343 /etc/hosts.allow and /etc/hosts.deny per default, see "man 5 hosts_access"
2344 for more information. The optional <name> (type link(string)(TYPE_STRING))
2345 is passed to the wrapper functions as daemon process name (link(example)(EXAMPLE_OPTION_TCPWRAPPERS)).
2346 If omitted, the basename of socats invocation (argv[0]) is passed.
2347 If both tcpwrap and range options are applied to an address, both
2348 conditions must be fulfilled to allow the connection.
2349 label(OPTION_TCPWRAP_HOSTS_ALLOW_TABLE)dit(bf(tt(allow-table=<filename>)))
2350 Takes the specified file instead of /etc/hosts.allow.
2351 label(OPTION_TCPWRAP_HOSTS_DENY_TABLE)dit(bf(tt(deny-table=<filename>)))
2352 Takes the specified file instead of /etc/hosts.deny.
2353 label(OPTION_TCPWRAP_ETC)dit(bf(tt(tcpwrap-etc=<directoryname>)))
2354 Looks for hosts.allow and hosts.deny in the specified directory. Is
2355 overridden by options link(hosts-allow)(OPTION_TCPWRAP_HOSTS_ALLOW_TABLE)
2356 and link(hosts-deny)(OPTION_TCPWRAP_HOSTS_DENY_TABLE).
2357 enddit()
2358  
2359 startdit()enddit()nl()
2360  
2361  
2362 label(GROUP_LISTEN)em(bf(LISTEN option group))
2363  
2364 Options specific to listening sockets.
2365 startdit()
2366 label(OPTION_BACKLOG)dit(bf(tt(backlog=<count>)))
2367 Sets the backlog value passed with the code(listen()) system call to <count>
2368 [link(int)(TYPE_INT)]. Default is 5.
2369 label(OPTION_MAX_CHILDREN)dit(bf(tt(max-children=<count>)))
2370 Limits the number of concurrent child processes [link(int)(TYPE_INT)].
2371 Default is no limit.
2372 enddit()
2373 startdit()enddit()nl()
2374  
2375  
2376 label(GROUP_CHILD)em(bf(CHILD option group))
2377  
2378 Options for addresses with multiple connections via child processes.
2379 startdit()
2380 label(OPTION_FORK)dit(bf(tt(fork)))
2381 After establishing a connection, handles its channel in a child process and
2382 keeps the parent process attempting to produce more connections, either by
2383 listening or by connecting in a loop (link(example)(EXAMPLE_OPTION_FORK)).nl()
2384 SSL-CONNECT and SSL-LISTEN differ in when they actually fork off the child:
2385 SSL-LISTEN forks em(before) the SSL handshake, while SSL-CONNECT forks
2386 em(afterwards).
2387 RETRY and FOREVER options are not inherited by the child process.nl()
2388 On some operating systems (e.g. FreeBSD) this option does not work for
2389 UDP-LISTEN addresses.nl()
2390 enddit()
2391  
2392 startdit()enddit()nl()
2393  
2394  
2395 label(GROUP_EXEC)em(bf(EXEC option group))
2396  
2397 Options for addresses that invoke a program.
2398 startdit()
2399 label(OPTION_PATH)dit(bf(tt(path=<string>)))
2400 Overrides the PATH environment variable for searching the program with
2401 link(<string>)(TYPE_STRING). This
2402 code($PATH) value is effective in the child process too.
2403 label(OPTION_LOGIN)dit(bf(tt(login)))
2404 Prefixes code(argv[0]) for the code(execvp()) call with '-', thus making a
2405 shell behave as login shell.
2406 enddit()
2407  
2408 startdit()enddit()nl()
2409  
2410  
2411 label(GROUP_FORK)em(bf(FORK option group))
2412  
2413 EXEC or SYSTEM addresses invoke a program using a child process and transfer data between socat() and the program. The interprocess communication mechanism can be influenced with the following options. Per
2414 default, a code(socketpair()) is created and assigned to stdin and stdout of
2415 the child process, while stderr is inherited from the socat() process, and the
2416 child process uses file descriptors 0 and 1 for communicating with the main
2417 socat() process.
2418 startdit()
2419 label(OPTION_NOFORK)dit(bf(tt(nofork)))
2420 Does not fork a subprocess for executing the program, instead calls execvp\()
2421 or system\() directly from the actual socat() instance. This avoids the
2422 overhead of another process between the program and its peer,
2423 but introduces a lot of restrictions:
2424 startit()
2425 it() this option can only be applied to the second socat() address.
2426 it() it cannot be applied to a part of a link(dual)(ADDRESS_DUAL) address.
2427 it() the first socat() address cannot be OPENSSL or READLINE
2428 it() socat() options -b, -t, -D, -l, -v, -x become useless
2429 it() for both addresses, options ignoreeof, cr, and crnl become useless
2430 it() for the second address (the one with option nofork), options
2431 append, metaCOMMENT(async,) cloexec, flock, user, group, mode, nonblock,
2432 perm-late, setlk, and setpgid cannot be applied. Some of these could be
2433 used on the first address though.
2434 endit()
2435 label(OPTION_COMMTYPE)dit(bf(tt(commtype=<commtype>)))
2436 Specifies the kind of file descriptors that are generated for communication
2437 between the socat() process and the left side of the program. See
2438 link(commtype)(TYPE_COMMTYPE) for supported values and their meanings.
2439 label(OPTION_PIPES)dit(bf(tt(pipes)))
2440 Creates a pair of unnamed pipes for interprocess communication instead of a
2441 socket pair (obsolete, use option link(commtype)(OPTION_COMMTYPE) instead).
2442 label(OPTION_OPENPTY)dit(bf(tt(openpty)))
2443 Establishes communication with the sub process using a pseudo terminal
2444 created with code(openpty()) instead of the default (socketpair or ptmx).
2445 label(OPTION_PTMX)dit(bf(tt(ptmx)))
2446 Establishes communication with the sub process using a pseudo terminal
2447 created by opening file(/dev/ptmx) or file(/dev/ptc) instead of the default
2448 (socketpair).
2449 label(OPTION_PTY)dit(bf(tt(pty)))
2450 Establishes communication with the sub process using a pseudo terminal
2451 instead of a socket pair. Creates the pty with an available mechanism. If
2452 openpty and ptmx are both available, it uses ptmx because this is POSIX
2453 compliant (obsolete, use option link(commtype)(OPTION_COMMTYPE) instead)
2454 (link(example)(EXAMPLE_OPTION_PTY)).
2455 label(OPTION_CTTY)dit(bf(tt(ctty)))
2456 Makes the pty the controlling tty of the sub process (link(example)(EXAMPLE_OPTION_CTTY)).
2457 label(OPTION_STDERR)dit(bf(tt(stderr)))
2458 Directs stderr of the sub process to its output channel by making stderr a
2459 code(dup()) of stdout (link(example)(EXAMPLE_OPTION_STDERR)).
2460 label(OPTION_FDIN)dit(bf(tt(fdin=<fdnum>)))
2461 Assigns the sub processes input channel to its file descriptor
2462 link(<fdnum>)(TYPE_FDNUM)
2463 instead of stdin (0). The program started from the subprocess has to use
2464 this fd for reading data from socat() (link(example)(EXAMPLE_OPTION_FDIN)).
2465 label(OPTION_FDOUT)dit(bf(tt(fdout=<fdnum>)))
2466 Assigns the sub processes output channel to its file descriptor
2467 link(<fdnum>)(TYPE_FDNUM)
2468 instead of stdout (1). The program started from the subprocess has to use
2469 this fd for writing data to socat() (link(example)(EXAMPLE_OPTION_FDOUT)).
2470 label(OPTION_SIGHUP)label(OPTION_SIGINT)label(OPTION_SIGQUIT)dit(bf(tt(sighup)), bf(tt(sigint)), bf(tt(sigquit)))
2471 Has socat() pass signals of this type to the sub process.
2472 If no address has this option, socat() terminates on these signals.
2473 enddit()
2474  
2475 startdit()enddit()nl()
2476  
2477  
2478 label(GROUP_TERMIOS)em(bf(TERMIOS option group))
2479  
2480 For addresses that work on a tty (e.g., stdio, file:/dev/tty, exec:...,pty), the terminal parameters defined in the unix() termios mechanism are made available as address option parameters.
2481 Please note that changes of the parameters of your interactive terminal
2482 remain effective after socat()'s termination, so you might have to enter "reset"
2483 or "stty sane" in your shell afterwards.
2484 For EXEC and SYSTEM addresses with option PTY,
2485 these options apply to the pty by the child processes.
2486  
2487 startdit()
2488 label(OPTION_B0)dit(bf(tt(b0)))
2489 Disconnects the terminal.
2490 label(OPTION_B19200)dit(bf(tt(b19200)))
2491 Sets the serial line speed to 19200 baud. Some other rates are possible; use
2492 something like tt(socat -hh |grep ' b[1-9]') to find all speeds supported by
2493 your implementation.nl()
2494 Note: On some operating systems, these options may not be
2495 available. Use link(ispeed)(OPTION_ISPEED) or link(ospeed)(OPTION_OSPEED)
2496 instead.
2497 label(OPTION_ECHO)dit(bf(tt(echo=<bool>)))
2498 Enables or disables local echo.
2499 label(OPTION_ICANON)dit(bf(tt(icanon=<bool>)))
2500 Sets or clears canonical mode, enabling line buffering and some special
2501 characters.
2502 label(OPTION_RAW)dit(bf(tt(raw)))
2503 Sets raw mode, thus passing input and output almost unprocessed. This option is obsolete, use option link(rawer)(OPTION_TERMIOS_RAWER) or link(cfmakeraw)(OPTION_TERMIOS_CFMAKERAW) instead.
2504 label(OPTION_TERMIOS_RAWER)dit(bf(tt(rawer)))
2505 Makes terminal rawer than link(raw)(OPTION_RAW) option. This option implicitly turns off echo. (link(example)(EXAMPLE_OPTION_TERMIOS_RAWER)).
2506 label(OPTION_TERMIOS_CFMAKERAW)dit(bf(tt(cfmakeraw)))
2507 Sets raw mode by invoking tt(cfmakeraw()) or by simulating this call. This option implicitly turns off echo.
2508 label(OPTION_IGNBRK)dit(bf(tt(ignbrk=<bool>)))
2509 Ignores or interpretes the BREAK character (e.g., ^C)
2510 label(OPTION_BRKINT)dit(bf(tt(brkint=<bool>)))
2511 label(OPTION_BS0)dit(bf(tt(bs0)))
2512 label(OPTION_BS1)dit(bf(tt(bs1)))
2513 label(OPTION_BSDLY)dit(bf(tt(bsdly=<0|1>)))
2514 label(OPTION_CLOCAL)dit(bf(tt(clocal=<bool>)))
2515  
2516 label(OPTION_CR0)label(OPTION_CR1)label(OPTION_CR2)label(OPTION_CR3)
2517 mancommand(\.LP)
2518 mancommand(\.nf)
2519 mancommand(\fBcr0
2520 cr1
2521 cr2
2522 cr3\fP)
2523 mancommand(\.fi)
2524 mancommand(\.IP)
2525 htmlcommand(<dt><code><strong>cr0</strong><br>
2526 <strong>cr1</strong><br>
2527 <strong>cr2</strong><br>
2528 <strong>cr3</strong></code><dd>)
2529 Sets the carriage return delay to 0, 1, 2, or 3, respectively.
2530  
2531  
2532 label(OPTION_CRDLY)dit(bf(tt(crdly=<0|1|2|3>)))
2533 label(OPTION_CREAD)dit(bf(tt(cread=<bool>)))
2534 label(OPTION_CRTSCTS)dit(bf(tt(crtscts=<bool>)))
2535  
2536 label(OPTION_CS5)label(OPTION_CS6)label(OPTION_CS7)label(OPTION_CS8)
2537 mancommand(\.LP)
2538 mancommand(\.nf)
2539 mancommand(\fBcs5
2540 cs6
2541 cs7
2542 cs8\fP)
2543 mancommand(\.fi)
2544 mancommand(\.IP)
2545 htmlcommand(<dt><code><strong>cs5</strong><br>
2546 <strong>cs6</strong><br>
2547 <strong>cs7</strong><br>
2548 <strong>cs8</strong></code><dd>)
2549 Sets the character size to 5, 6, 7, or 8 bits, respectively.
2550  
2551 label(OPTION_CSIZE)dit(bf(tt(csize=<0|1|2|3>)))
2552 label(OPTION_CSTOPB)dit(bf(tt(cstopb=<bool>)))
2553 Sets two stop bits, rather than one.
2554 label(OPTION_VDSUSP)dit(bf(tt(dsusp=<byte>)))
2555 Sets the value for the VDSUSP character that suspends the current foreground
2556 process and reactivates the shell (all except Linux).
2557 label(OPTION_ECHOCTL)dit(bf(tt(echoctl=<bool>)))
2558 Echos control characters in hat notation (e.g. ^A)
2559 label(OPTION_ECHOE)dit(bf(tt(echoe=<bool>)))
2560 label(OPTION_ECHOK)dit(bf(tt(echok=<bool>)))
2561 label(OPTION_ECHOKE)dit(bf(tt(echoke=<bool>)))
2562 label(OPTION_ECHONL)dit(bf(tt(echonl=<bool>)))
2563 label(OPTION_ECHOPRT)dit(bf(tt(echoprt=<bool>)))
2564 label(OPTION_EOF)dit(bf(tt(eof=<byte>)))
2565 label(OPTION_EOL)dit(bf(tt(eol=<byte>)))
2566 label(OPTION_EOL2)dit(bf(tt(eol2=<byte>)))
2567 label(OPTION_ERASE)dit(bf(tt(erase=<byte>)))
2568 label(OPTION_DISCARD)dit(bf(tt(discard=<byte>)))
2569 label(OPTION_FF0)dit(bf(tt(ff0)))
2570 label(OPTION_FF1)dit(bf(tt(ff1)))
2571 label(OPTION_FFDLY)dit(bf(tt(ffdly=<bool>)))
2572 label(OPTION_FLUSHO)dit(bf(tt(flusho=<bool>)))
2573 label(OPTION_HUPCL)dit(bf(tt(hupcl=<bool>)))
2574 label(OPTION_ICRNL)dit(bf(tt(icrnl=<bool>)))
2575 label(OPTION_IEXTEN)dit(bf(tt(iexten=<bool>)))
2576 label(OPTION_IGNCR)dit(bf(tt(igncr=<bool>)))
2577 label(OPTION_IGNPAR)dit(bf(tt(ignpar=<bool>)))
2578 label(OPTION_IMAXBEL)dit(bf(tt(imaxbel=<bool>)))
2579 label(OPTION_INLCR)dit(bf(tt(inlcr=<bool>)))
2580 label(OPTION_INPCK)dit(bf(tt(inpck=<bool>)))
2581 label(OPTION_INTR)dit(bf(tt(intr=<byte>)))
2582 label(OPTION_ISIG)dit(bf(tt(isig=<bool>)))
2583 label(OPTION_ISPEED)dit(bf(tt(ispeed=<unsigned-int>)))
2584 Set the baud rate for incoming data on this line.nl()
2585 See also: link(ospeed)(OPTION_OSPEED), link(b19200)(OPTION_B19200)
2586 label(OPTION_ISTRIP)dit(bf(tt(istrip=<bool>)))
2587 label(OPTION_IUCLC)dit(bf(tt(iuclc=<bool>)))
2588 label(OPTION_IXANY)dit(bf(tt(ixany=<bool>)))
2589 label(OPTION_IXOFF)dit(bf(tt(ixoff=<bool>)))
2590 label(OPTION_IXON)dit(bf(tt(ixon=<bool>)))
2591 label(OPTION_KILL)dit(bf(tt(kill=<byte>)))
2592 label(OPTION_LNEXT)dit(bf(tt(lnext=<byte>)))
2593 label(OPTION_MIN)dit(bf(tt(min=<byte>)))
2594 label(OPTION_NL0)dit(bf(tt(nl0)))
2595 Sets the newline delay to 0.
2596 label(OPTION_NL1)dit(bf(tt(nl1)))
2597 label(OPTION_NLDLY)dit(bf(tt(nldly=<bool>)))
2598 label(OPTION_NOFLSH)dit(bf(tt(noflsh=<bool>)))
2599 label(OPTION_OCRNL)dit(bf(tt(ocrnl=<bool>)))
2600 label(OPTION_OFDEL)dit(bf(tt(ofdel=<bool>)))
2601 label(OPTION_OFILL)dit(bf(tt(ofill=<bool>)))
2602 label(OPTION_OLCUC)dit(bf(tt(olcuc=<bool>)))
2603 label(OPTION_ONLCR)dit(bf(tt(onlcr=<bool>)))
2604 label(OPTION_ONLRET)dit(bf(tt(onlret=<bool>)))
2605 label(OPTION_ONOCR)dit(bf(tt(onocr=<bool>)))
2606 label(OPTION_OPOST)dit(bf(tt(opost=<bool>)))
2607 Enables or disables output processing; e.g., converts NL to CR-NL.
2608 label(OPTION_OSPEED)dit(bf(tt(ospeed=<unsigned-int>)))
2609 Set the baud rate for outgoing data on this line.nl()
2610 See also: link(ispeed)(OPTION_ISPEED), link(b19200)(OPTION_B19200)
2611 label(OPTION_PARENB)dit(bf(tt(parenb=<bool>)))
2612 Enable parity generation on output and parity checking for input.
2613 label(OPTION_PARMRK)dit(bf(tt(parmrk=<bool>)))
2614 label(OPTION_PARODD)dit(bf(tt(parodd=<bool>)))
2615 label(OPTION_PENDIN)dit(bf(tt(pendin=<bool>)))
2616 label(OPTION_QUIT)dit(bf(tt(quit=<byte>)))
2617 label(OPTION_REPRINT)dit(bf(tt(reprint=<byte>)))
2618 label(OPTION_SANE)dit(bf(tt(sane)))
2619 Brings the terminal to something like a useful default state.
2620 label(OPTION_START)dit(bf(tt(start=<byte>)))
2621 label(OPTION_STOP)dit(bf(tt(stop=<byte>)))
2622 label(OPTION_SUSP)dit(bf(tt(susp=<byte>)))
2623 label(OPTION_SWTC)dit(bf(tt(swtc=<byte>)))
2624 label(OPTION_TAB0)dit(bf(tt(tab0)))
2625 label(OPTION_TAB1)dit(bf(tt(tab1)))
2626 label(OPTION_TAB2)dit(bf(tt(tab2)))
2627 label(OPTION_TAB3)dit(bf(tt(tab3)))
2628 label(OPTION_TABDLY)dit(bf(tt(tabdly=<unsigned-int>)))
2629 label(OPTION_TIME)dit(bf(tt(time=<byte>)))
2630 label(OPTION_TOSTOP)dit(bf(tt(tostop=<bool>)))
2631 label(OPTION_VT0)dit(bf(tt(vt0)))
2632 label(OPTION_VT1)dit(bf(tt(vt1)))
2633 label(OPTION_VTDLY)dit(bf(tt(vtdly=<bool>)))
2634 label(OPTION_WERASE)dit(bf(tt(werase=<byte>)))
2635 label(OPTION_XCASE)dit(bf(tt(xcase=<bool>)))
2636 label(OPTION_XTABS)dit(bf(tt(xtabs)))
2637 label(OPTION_I_POP_ALL)dit(bf(tt(i-pop-all)))
2638 With UNIX System V STREAMS, removes all drivers from the stack.
2639 label(OPTION_I_PUSH)dit(bf(tt(i-push=<string>)))
2640 With UNIX System V STREAMS, pushes the driver (module) with the given name
2641 (link(string)(TYPE_STRING)) onto the stack. For example, to make sure that a
2642 character device on Solaris supports termios etc, use the following options:
2643 tt(i-pop-all,i-push=ptem,i-push=ldterm,i-push=ttcompat)
2644 enddit()
2645  
2646 startdit()enddit()nl()
2647  
2648  
2649 label(GROUP_PTY)em(bf(PTY option group))
2650  
2651 These options are intended for use with the link(pty)(ADDRESS_PTY) address
2652 type.
2653  
2654 startdit()
2655 label(OPTION_SYMBOLIC_LINK)dit(bf(tt(link=<filename>)))
2656 Generates a symbolic link that points to the actual pseudo terminal
2657 (pty). This might help
2658 to solve the problem that ptys are generated with more or less
2659 unpredictable names, making it difficult to directly access the socat
2660 generated pty automatically. With this option, the user can specify a "fix"
2661 point in the file hierarchy that helps him to access the actual pty
2662 (link(example)(EXAMPLE_OPTION_SYMBOLIC_LINK)).
2663 Beginning with socat() version 1.4.3, the symbolic link is removed when
2664 the address is closed (but see option link(unlink-close)(OPTION_UNLINK_CLOSE)).
2665 label(OPTION_PTY_WAIT_SLAVE)dit(bf(tt(wait-slave)))
2666 Blocks the open phase until a process opens the slave side of the pty.
2667 Usually, socat() continues after generating the pty with opening the next
2668 address or with entering the transfer loop. With the wait-slave option,
2669 socat() waits until some process opens the slave side of the pty before
2670 continuing.
2671 This option only works if the operating system provides the tt(poll())
2672 system call. And it depends on an undocumented behaviour of pty's, so it
2673 does not work on all operating systems. It has successfully been tested on
2674 Linux, FreeBSD, NetBSD, and on Tru64 with openpty.
2675 label(OPTION_PTY_INTERVAL)dit(bf(tt(pty-interval=<seconds>)))
2676 When the link(wait-slave)(OPTION_PTY_WAIT_SLAVE) option is set, socat
2677 periodically checks the HUP condition using tt(poll()) to find if the pty's
2678 slave side has been opened. The default polling interval is 1s. Use the
2679 pty-interval option [link(timeval)(TYPE_TIMEVAL)] to change this value.
2680 enddit()
2681  
2682  
2683 startdit()enddit()nl()
2684  
2685  
2686 label(GROUP_OPENSSL)em(bf(OPENSSL option group))
2687  
2688 These options apply to the link(openssl)(ADDRESS_OPENSSL_CONNECT) and
2689 link(openssl-listen)(ADDRESS_OPENSSL_LISTEN) address types.
2690  
2691 startdit()
2692 label(OPTION_OPENSSL_CIPHERLIST)dit(bf(tt(cipher=<cipherlist>)))
2693 Selects the list of ciphers that may be used for the connection.
2694 See the man page of code(ciphers), section bf(CIPHER LIST FORMAT), for
2695 detailed information about syntax, values, and default of <cipherlist>.nl()
2696 Several cipher strings may be given, separated by ':'.
2697 Some simple cipher strings:
2698 startdit()
2699 dit(3DES) Uses a cipher suite with triple DES.
2700 dit(MD5) Uses a cipher suite with MD5.
2701 dit(aNULL) Uses a cipher suite without authentication.
2702 dit(NULL) Does not use encryption.
2703 dit(HIGH) Uses a cipher suite with "high" encryption.
2704 enddit()
2705 Note that the peer must support the selected property, or the negotiation
2706 will fail.
2707 label(OPTION_OPENSSL_METHOD)dit(bf(tt(method=<ssl-method>)))
2708 Sets the protocol version to be used. Valid strings (not case sensitive)
2709 are:
2710 startdit()
2711 dit(tt(SSL2)) Select SSL protocol version 2.
2712 dit(tt(SSL3)) Select SSL protocol version 3.
2713 dit(tt(SSL23)) Select the best available SSL or TLS protocol. This is the default when
2714 this option is not provided.
2715 dit(tt(TLS1)) Select TLS protocol version 1.
2716 dit(tt(TLS1.1)) Select TLS protocol version 1.1.
2717 dit(tt(TLS1.2)) Select TLS protocol version 1.2.
2718 dit(tt(DTLS1)) Select DTLS protocol version 1.
2719 enddit()
2720 label(OPTION_OPENSSL_VERIFY)dit(bf(tt(verify=<bool>)))
2721 Controls check of the peer's certificate. Default is 1 (true). Disabling
2722 verify might open your socket for everyone, making the encryption useless!
2723 label(OPTION_OPENSSL_CERTIFICATE)dit(bf(tt(cert=<filename>)))
2724 Specifies the file with the certificate and private key for authentication.
2725 The certificate must be in OpenSSL format (*.pem).
2726 With openssl-listen, use of this option is strongly
2727 recommended. Except with cipher aNULL, "no shared ciphers" error will
2728 occur when no certificate is given.
2729 label(OPTION_OPENSSL_KEY)dit(bf(tt(key=<filename>)))
2730 Specifies the file with the private key. The private key may be in this
2731 file or in the file given with the link(cert)(OPTION_OPENSSL_CERTIFICATE) option. The party that has
2732 to proof that it is the owner of a certificate needs the private key.
2733 label(OPTION_OPENSSL_DHPARAMS)dit(bf(tt(dhparams=<filename>)))
2734 Specifies the file with the Diffie Hellman parameters. These parameters may
2735 also be in the file given with the link(cert)(OPTION_OPENSSL_CERTIFICATE)
2736 option in which case the dhparams option is not needed.
2737 label(OPTION_OPENSSL_CAFILE)dit(bf(tt(cafile=<filename>)))
2738 Specifies the file with the trusted (root) authority certificates. The file
2739 must be in PEM format and should contain one or more certificates. The party
2740 that checks the authentication of its peer trusts only certificates that are
2741 in this file.
2742 label(OPTION_OPENSSL_CAPATH)dit(bf(tt(capath=<dirname>)))
2743 Specifies the directory with the trusted (root) certificates. The directory
2744 must contain certificates in PEM format and their hashes (see OpenSSL
2745 documentation)
2746 label(OPTION_OPENSSL_EGD)dit(bf(tt(egd=<filename>)))
2747 On some systems, openssl requires an explicit source of random data. Specify
2748 the socket name where an entropy gathering daemon like egd provides random
2749 data, e.g. /dev/egd-pool.
2750 label(OPTION_OPENSSL_PSEUDO)dit(bf(tt(pseudo)))
2751 On systems where openssl cannot find an entropy source and where no entropy
2752 gathering daemon can be utilized, this option activates a mechanism for
2753 providing pseudo entropy. This is archieved by taking the current time in
2754 microseconds for feeding the libc pseudo random number generator with an
2755 initial value. openssl is then feeded with output from random\() calls.nl()
2756 NOTE: This mechanism is not sufficient for generation of secure keys!
2757 label(OPTION_OPENSSL_FIPS)dit(bf(tt(fips)))
2758 Enables FIPS mode if compiled in. For info about the FIPS encryption
2759 implementation standard see lurl(http://oss-institute.org/fips-faq.html).
2760 This mode might require that the involved certificates are generated with a
2761 FIPS enabled version of openssl. Setting or clearing this option on one
2762 socat() address affects all OpenSSL addresses of this process.
2763 label(OPTION_OPENSSL_COMPRESS)dit(bf(tt(compress)))
2764 Enable or disable the use of compression for a connection. Setting this to
2765 "none" disables compression, setting it to "auto" lets OpenSSL choose the best
2766 available algorithm supported by both parties. The default is to not touch any
2767 compression-related settings.
2768 NOTE: Requires OpenSSL 0.9.8 or higher and disabling compression with
2769 OpenSSL 0.9.8 affects all new connections in the process.
2770 label(OPTION_OPENSSL_COMMONNAME)dit(bf(tt(commonname=<string>)))
2771 Specify the commonname that the peer certificate must match. With
2772 link(OPENSSL-CONNECT)(ADDRESS_OPENSSL_CONNECT) address this overrides the
2773 given hostname or IP target address; with
2774 link(OPENSSL-LISTEN)(ADDRESS_OPENSSL_LISTEN) this turns on check of peer
2775 certificates commonname. This option has only meaning when option
2776 link(verify)(OPTION_OPENSSL_VERIFY) is not disabled and the choosen cipher
2777 provides a peer certificate.
2778 enddit()
2779  
2780 startdit()enddit()nl()
2781  
2782  
2783 label(GROUP_RETRY)em(bf(RETRY option group))
2784  
2785 Options that control retry of some system calls, especially connection
2786 attempts.
2787  
2788 startdit()
2789 label(OPTION_RETRY)dit(bf(tt(retry=<num>)))
2790 Number of retries before the connection or listen attempt is aborted.
2791 Default is 0, which means just one attempt.
2792 label(OPTION_INTERVAL)dit(bf(tt(interval=<timespec>)))
2793 Time between consecutive attempts (seconds,
2794 [link(timespec)(TYPE_TIMESPEC)]). Default is 1 second.
2795 label(OPTION_FOREVER)dit(bf(tt(forever)))
2796 Performs an unlimited number of retry attempts.
2797 enddit()
2798  
2799 startdit()enddit()nl()
2800  
2801  
2802 label(GROUP_TUN)em(bf(TUN option group))
2803  
2804 Options that control Linux TUN/TAP interface device addresses.
2805  
2806 startdit()
2807 label(OPTION_TUN_DEVICE)dit(bf(tt(tun-device=<device-file>)))
2808 Instructs socat() to take another path for the TUN clone device. Default is
2809 tt(/dev/net/tun).
2810 label(OPTION_TUN_NAME)dit(bf(tt(tun-name=<if-name>)))
2811 Gives the resulting network interface a specific name instead of the system
2812 generated (tun0, tun1, etc.)
2813 label(OPTION_TUN_TYPE)dit(bf(tt(tun-type=[tun|tap])))
2814 Sets the type of the TUN device; use this option to generate a TAP
2815 device. See the Linux docu for the difference between these types.
2816 When you try to establish a tunnel between two TUN devices, their types
2817 should be the same.
2818 label(OPTION_IFF_NO_PI)dit(bf(tt(iff-no-pi)))
2819 Sets the IFF_NO_PI flag which controls if the device includes additional
2820 packet information in the tunnel.
2821 When you try to establish a tunnel between two TUN devices, these flags
2822 should have the same values.
2823 label(OPTION_IFF_UP)dit(bf(tt(iff-up)))
2824 Sets the TUN network interface status UP. Strongly recommended.
2825 label(OPTION_IFF_BROADCAST)dit(bf(tt(iff-broadcast)))
2826 Sets the BROADCAST flag of the TUN network interface.
2827 label(OPTION_IFF_DEBUG)dit(bf(tt(iff-debug)))
2828 Sets the DEBUG flag of the TUN network interface.
2829 label(OPTION_IFF_LOOPBACK)dit(bf(tt(iff-loopback)))
2830 Sets the LOOPBACK flag of the TUN network interface.
2831 label(OPTION_IFF_POINTOPOINT)dit(bf(tt(iff-pointopoint)))
2832 Sets the POINTOPOINT flag of the TUN device.
2833 label(OPTION_IFF_NOTRAILERS)dit(bf(tt(iff-notrailers)))
2834 Sets the NOTRAILERS flag of the TUN device.
2835 label(OPTION_IFF_RUNNING)dit(bf(tt(iff-running)))
2836 Sets the RUNNING flag of the TUN device.
2837 label(OPTION_IFF_NOARP)dit(bf(tt(iff-noarp)))
2838 Sets the NOARP flag of the TUN device.
2839 label(OPTION_IFF_PROMISC)dit(bf(tt(iff-promisc)))
2840 Sets the PROMISC flag of the TUN device.
2841 label(OPTION_IFF_ALLMULTI)dit(bf(tt(iff-allmulti)))
2842 Sets the ALLMULTI flag of the TUN device.
2843 label(OPTION_IFF_MASTER)dit(bf(tt(iff-master)))
2844 Sets the MASTER flag of the TUN device.
2845 label(OPTION_IFF_SLAVE)dit(bf(tt(iff-slave)))
2846 Sets the SLAVE flag of the TUN device.
2847 label(OPTION_IFF_MULTICAST)dit(bf(tt(iff-multicast)))
2848 Sets the MULTICAST flag of the TUN device.
2849 label(OPTION_IFFPORTSEL_)dit(bf(tt(iff-portsel)))
2850 Sets the PORTSEL flag of the TUN device.
2851 label(OPTION_IFF_AUTOMEDIA)dit(bf(tt(iff-automedia)))
2852 Sets the AUTOMEDIA flag of the TUN device.
2853 label(OPTION_IFF_DYNAMIC)dit(bf(tt(iff-dynamic)))
2854 Sets the DYNAMIC flag of the TUN device.
2855 enddit()
2856  
2857 startdit()enddit()nl()
2858  
2859  
2860 label(VALUES)
2861 manpagesection(DATA VALUES)
2862  
2863 This section explains the different data types that address parameters and
2864 address options can take.
2865  
2866 startdit()
2867 label(TYPE_ADDRESS_RANGE)dit(address-range)
2868 Is currently only implemented for IPv4 and IPv6. See address-option
2869 link(`range')(OPTION_RANGE)
2870 label(TYPE_BOOL)dit(bool)
2871 "0" or "1"; if value is omitted, "1" is taken.
2872 label(TYPE_BYTE)dit(byte)
2873 An unsigned int number, read with code(strtoul()), lower or equal to
2874 code(UCHAR_MAX).
2875 label(TYPE_COMMAND_LINE)dit(command-line)
2876 A string specifying a program name and its arguments, separated by single
2877 spaces.
2878 label(TYPE_COMMTYPE)dit(commtype)
2879 One of the following supported strings:
2880 startdit()
2881 label(TYPE_COMMTYPE_SOCKETPAIR)dit(bf(tt(socketpair)))A single UNIX domain
2882 socket pair.
2883 label(TYPE_COMMTYPE_SOCKETPAIRS)dit(bf(tt(socketpairs)))Two UNIX domain
2884 socket pairs for bidirectional transfer, or one in case of unidirectional
2885 transfer. This type is the default.
2886 label(TYPE_COMMTYPE_PIPES)dit(bf(tt(pipes)))Two pipes, or one in case of
2887 unidirectional transfer.
2888 label(TYPE_COMMTYPE_TCP)dit(bf(tt(tcp)))One pair of TCP sockets.
2889 label(TYPE_COMMTYPE_PTYS)dit(bf(tt(ptys)))Two PTYs or one in case of
2890 unidirectional transfer. The slave sides are used for writing.
2891 enddit()
2892 label(TYPE_DATA)dit(data)
2893 A raw data specification following em(dalan) syntax. Currently the only
2894 valid form is a string starting with 'x' followed by an even number of hex
2895 digits, specifying a sequence of bytes.
2896 label(TYPE_DIRECTORY)dit(directory)
2897 A string with usual unix() directory name semantics.
2898 label(TYPE_FACILITY)dit(facility)
2899 The name of a syslog facility in lower case characters.
2900 label(TYPE_FDNUM)dit(fdnum)
2901 An unsigned int type, read with code(strtoul()), specifying a unix() file
2902 descriptor.
2903 label(TYPE_FILENAME)dit(filename)
2904 A string with usual unix() filename semantics.
2905 label(TYPE_GROUP)dit(group)
2906 If the first character is a decimal digit, the value is read with
2907 code(strtoul()) as unsigned integer specifying a group id. Otherwise, it
2908 must be an existing group name.
2909 label(TYPE_INT)dit(int)
2910 A number following the rules of the code(strtol()) function with base
2911 "0", i.e. decimal number, octal number with leading "0", or hexadecimal
2912 number with leading "0x". The value must fit into a C int.
2913 label(TYPE_INTERFACE)dit(interface)
2914 A string specifying the device name of a network interface
2915 as shown by ifconfig or procan, e.g. "eth0".
2916 label(TYPE_IP_ADDRESS)dit(IP address)
2917 An IPv4 address in numbers-and-dots notation, an IPv6 address in hex
2918 notation enclosed in brackets, or a hostname that resolves to an IPv4 or an
2919 IPv6 address.nl()
2920 Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1
2921 label(TYPE_IPV4_ADDRESS)dit(IPv4 address)
2922 An IPv4 address in numbers-and-dots notation or a hostname that resolves to
2923 an IPv4 address.nl()
2924 Examples: 127.0.0.1, www.dest-unreach.org, dns2
2925 label(TYPE_IPV6_ADDRESS)dit(IPv6 address)
2926 An iPv6 address in hexnumbers-and-colons notation enclosed in brackets, or a
2927 hostname that resolves to an IPv6 address.nl()
2928 Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0],
2929 ip6name.domain.org
2930 label(TYPE_LONG)dit(long)
2931 A number read with code(strtol()). The value must fit into a C long.
2932 label(TYPE_LONGLONG)dit(long long)
2933 A number read with code(strtoll()). The value must fit into a C long long.
2934 label(TYPE_OFF)dit(off_t)
2935 An implementation dependend signed number, usually 32 bits, read with strtol
2936 or strtoll.
2937 label(TYPE_OFF64)dit(off64_t)
2938 An implementation dependend signed number, usually 64 bits, read with strtol
2939 or strtoll.
2940 label(TYPE_MODE_T)dit(mode_t)
2941 An unsigned integer, read with code(strtoul()), specifying mode (permission)
2942 bits.
2943 label(TYPE_PID_T)dit(pid_t)
2944 A number, read with code(strtol()), specifying a process id.
2945 label(TYPE_PORT)dit(port)
2946 A uint16_t (16 bit unsigned number) specifying a TCP or UDP port, read
2947 with code(strtoul()).
2948 label(TYPE_PROTOCOL)dit(protocol)
2949 An unsigned 8 bit number, read with code(strtoul()).
2950 label(TYPE_SIZE_T)dit(size_t)
2951 An unsigned number with size_t limitations, read with code(strtoul).
2952 label(TYPE_SOCKNAME)dit(sockname)
2953 A socket address. See address-option link(`bind')(OPTION_BIND)
2954 label(TYPE_STRING)dit(string)
2955 A sequence of characters, not containing '\0' and, depending on
2956 the position within the command line, ':', ',', or "%". Note
2957 that you might have to escape shell meta characters in the command line.
2958 label(TYPE_TCP_SERVICE)dit(TCP service)
2959 A service name, not starting with a digit, that is resolved by
2960 code(getservbyname()), or an unsigned int 16 bit number read with
2961 code(strtoul()).
2962 label(TYPE_TIMEVAL)dit(timeval)
2963 A double float specifying seconds; the number is mapped into a
2964 struct timeval, consisting of seconds and microseconds.
2965 label(TYPE_TIMESPEC)dit(timespec)
2966 A double float specifying seconds; the number is mapped into a
2967 struct timespec, consisting of seconds and nanoseconds.
2968 label(TYPE_UDP_SERVICE)dit(UDP service)
2969 A service name, not starting with a digit, that is resolved by
2970 code(getservbyname()), or an unsigned int 16 bit number read with
2971 code(strtoul()).
2972 label(TYPE_UNSIGNED_INT)dit(unsigned int)
2973 A number read with code(strtoul()). The value must fit into a C unsigned
2974 int.
2975 label(TYPE_USER)dit(user)
2976 If the first character is a decimal digit, the value is read with
2977 code(strtoul()) as unsigned integer specifying a user id. Otherwise, it must
2978 be an existing user name.
2979 enddit()
2980  
2981  
2982 label(EXAMPLES)
2983 manpagesection(EXAMPLES)
2984  
2985  
2986 startdit()
2987  
2988 label(EXAMPLE_ADDRESS_TCP4_CONNECT)
2989 dit(bf(tt(socat - TCP4:www.domain.org:80)))
2990  
2991 transfers data between link(STDIO)(ADDRESS_STDIO) (-) and a
2992 link(TCP4)(ADDRESS_TCP4_CONNECT) connection to port 80 of host
2993 www.domain.org. This example results in an interactive connection similar to
2994 telnet or netcat. The stdin terminal parameters are not changed, so you may
2995 close the relay with ^D or abort it with ^C.
2996  
2997 label(EXAMPLE_ADDRESS_READLINE)
2998 label(EXAMPLE_OPTION_HISTORY)
2999 mancommand(\.LP)
3000 mancommand(\.nf)
3001 mancommand(\fBsocat -d -d READLINE,history=$HOME/.http_history \\
3002 TCP4:www.domain.org:www,crnl\fP)
3003 mancommand(\.fi)
3004  
3005 htmlcommand(<dt><code><strong>socat -d -d READLINE,history=$HOME/.http_history \</strong><br>
3006 <strong>TCP4:www.domain.org:www,crnl</strong></code><dd>)
3007  
3008 this is similar to the previous example, but you can edit the current line in a
3009 bash like manner (link(READLINE)(ADDRESS_READLINE)) and use the
3010 link(history)(OPTION_HISTORY) file .http_history; socat() prints messages about
3011 progress (link(-d -d)(option_d_d)). The port is specified by service name
3012 (www), and correct network line termination characters
3013 (link(crnl)(OPTION_CRNL)) instead of NL are used.
3014  
3015  
3016 label(EXAMPLE_ADDRESS_TCP4_LISTEN)
3017 dit(bf(tt(socat TCP4-LISTEN:www TCP4:www.domain.org:www)))
3018  
3019 installs a simple TCP port forwarder. With
3020 link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN) it listens on local port "www" until a
3021 connection comes in, accepts it, then connects to the remote host
3022 (link(TCP4)(ADDRESS_TCP4_CONNECT)) and starts data transfer. It will not accept
3023 a econd connection.
3024  
3025 label(EXAMPLE_OPTION_BIND_TCP4)
3026 label(EXAMPLE_OPTION_REUSEADDR)
3027 label(EXAMPLE_OPTION_FORK)
3028 label(EXAMPLE_OPTION_SUBSTUSER)
3029 label(EXAMPLE_OPTION_RANGE)
3030 mancommand(\.LP)
3031 mancommand(\.nf)
3032 mancommand(\fBsocat -d -d -lmlocal2 \\
3033 TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \\
3034 TCP4:www.domain.org:80,bind=myaddr2\fP)
3035 mancommand(\.fi)
3036  
3037 htmlcommand(<dt><code><strong>socat -d -d -lmlocal2 \</strong><br>
3038 <strong>TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \</strong><br>
3039 <strong>TCP4:www.domain.org:80,bind=myaddr2</strong></code><dd>)
3040  
3041 TCP port forwarder, each side bound to another local IP address
3042 (link(bind)(OPTION_BIND)). This example handles an almost
3043 arbitrary number of parallel or consecutive connections by
3044 link(fork)(OPTION_FORK)'ing a new
3045 process after each code(accept()). It provides a little security by
3046 link(su)(OPTION_SUBSTUSER)'ing to user
3047 nobody after forking; it only permits connections from the private 10 network
3048 (link(range)(OPTION_RANGE)); due to link(reuseaddr)(OPTION_REUSEADDR), it
3049 allows immediate restart after master process's termination, even if some child
3050 sockets are not completely shut down.
3051 With link(-lmlocal2)(option_lm), socat() logs to stderr until successfully
3052 reaching the accept loop. Further logging is directed to syslog with facility
3053 local2.
3054  
3055 label(EXAMPLE_ADDRESS_EXEC)
3056 label(EXAMPLE_OPTION_TCPWRAPPERS)
3057 label(EXAMPLE_OPTION_CHROOT)
3058 label(EXAMPLE_OPTION_SUBSTUSER_DELAYED)
3059 label(EXAMPLE_OPTION_PTY)
3060 label(EXAMPLE_OPTION_STDERR)
3061 mancommand(\.LP)
3062 mancommand(\.nf)
3063 mancommand(\fBsocat TCP4-LISTEN:5555,fork,tcpwrap=script \\
3064 EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr\fP)
3065 mancommand(\.fi)
3066  
3067 htmlcommand(<dt><code><strong>socat TCP4-LISTEN:5555,fork,tcpwrap=script \</strong><br>
3068 <strong>EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr</strong></code><dd>)
3069  
3070 a simple server that accepts connections
3071 (link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN)) and link(fork)(OPTION_FORK)'s a new
3072 child process for each connection; every child acts as single relay.
3073 The client must match the rules for daemon process name "script" in
3074 /etc/hosts.allow and /etc/hosts.deny, otherwise it is refused access (see "man
3075 5 hosts_access").
3076 For link(EXEC)(ADDRESS_EXEC)'uting the program, the child process
3077 link(chroot)(OPTION_CHROOT)'s
3078 to file(/home/sandbox), link(su)(OPTION_SUBSTUSER)'s to user sandbox, and then starts
3079 the program file(/home/sandbox/bin/myscript). Socat() and
3080 myscript communicate via a pseudo tty (link(pty)(OPTION_PTY)); myscript's
3081 link(stderr)(OPTION_STDERR) is redirected to stdout,
3082 so its error messages are transferred via socat() to the connected client.
3083  
3084 label(EXAMPLE_OPTION_FDIN)
3085 label(EXAMPLE_OPTION_FDOUT)
3086 label(EXAMPLE_OPTION_CRNL)
3087 label(EXAMPLE_OPTION_MSS)
3088 mancommand(\.LP)
3089 mancommand(\.nf)
3090 mancommand(\fBsocat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \\
3091 TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512\fP)
3092 mancommand(\.fi)
3093  
3094 htmlcommand(<dt><code><strong>socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \</strong><br>
3095 <strong>TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512</strong></code><dd>)
3096  
3097 file(mail.sh) is a shell script, distributed with socat(), that implements a
3098 simple
3099 SMTP client. It is programmed to "speak" SMTP on its FDs 3 (in) and 4 (out).
3100 The link(fdin)(OPTION_FDIN) and link(fdout)(OPTION_FDOUT) options tell socat()
3101 to use these FDs for communication with
3102 the program. Because mail.sh inherits stdin and stdout while socat() does not
3103 use them, the script can read a
3104 mail body from stdin. Socat() makes alias1 your local source address
3105 (link(bind)(OPTION_BIND)), cares for correct network line termination
3106 (link(crnl)(OPTION_CRNL)) and sends
3107 at most 512 data bytes per packet (link(mss)(OPTION_MSS)).
3108  
3109  
3110 label(EXAMPLE_ADDRESS_GOPEN)
3111 label(EXAMPLE_OPTION_TERMIOS_RAWER)
3112 label(EXAMPLE_OPTION_ESCAPE)
3113 dit(bf(tt(socat -,escape=0x0f /dev/ttyS0,rawer,crnl)))
3114  
3115 opens an interactive connection via the serial line, e.g. for talking with a
3116 modem. link(rawer)(OPTION_TERMIOS_RAWER) sets the console's and
3117 ttyS0's terminal parameters to practicable values, link(crnl)(OPTION_CRNL)
3118 converts to correct newline characters. link(escape)(OPTION_ESCAPE) allows to
3119 terminate the socat() process with character control-O.
3120 Consider using link(READLINE)(ADDRESS_READLINE) instead of the first address.
3121  
3122  
3123 label(EXAMPLE_ADDRESS_UNIX_LISTEN)
3124 label(EXAMPLE_ADDRESS_SOCKS4)
3125 label(EXAMPLE_OPTION_SOCKSUSER)
3126 label(EXAMPLE_OPTION_SOURCEPORT)
3127 mancommand(\.LP)
3128 mancommand(\.nf)
3129 mancommand(\fBsocat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \\
3130 SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20\fP)
3131 mancommand(\.fi)
3132  
3133 htmlcommand(<dt><code><strong>socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \</strong><br>
3134 <strong>SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20</strong></code><dd>)
3135  
3136 with link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), socat() opens a listening
3137 unixdomain() socket file(/tmp/.X11-unix/X1). This path corresponds
3138 to local XWindow display :1 on your machine, so XWindow client connections to
3139 DISPLAY=:1 are accepted. Socat() then speaks with
3140 the link(SOCKS4)(ADDRESS_SOCKS4) server host.victim.org that might permit
3141 link(sourceport)(OPTION_SOURCEPORT) 20 based connections due to an FTP related
3142 weakness in its static IP filters. Socat()
3143 pretends to be invoked by link(socksuser)(OPTION_SOCKSUSER) nobody, and
3144 requests to be connected to
3145 loopback port 6000 (only weak sockd configurations will allow this). So we get
3146 a connection to the victims XWindow server and, if it does not require MIT
3147 cookies or Kerberos authentication, we can start work. Please note that there
3148 can only be one connection at a time, because TCP can establish only one
3149 session with a given set of addresses and ports.
3150  
3151  
3152 label(EXAMPLE_option_u)
3153 label(EXAMPLE_OPTION_IGNOREEOF)
3154 dit(bf(tt(socat -u /tmp/readdata,seek-end=0,ignoreeof -)))
3155  
3156 this is an example for unidirectional data transfer
3157 (link(-u)(option_u)). Socat() transfers data
3158 from file /tmp/readdata (implicit address link(GOPEN)(ADDRESS_GOPEN)), starting
3159 at its current end (link(seek-end)(OPTION_SEEK_END)=0 lets socat() start
3160 reading at current end of file; use link(seek)(OPTION_SEEK)=0 or no
3161 seek option to first read the existing data) in a "tail -f" like mode
3162 (link(ignoreeof)(OPTION_IGNOREEOF)). The "file"
3163 might also be a listening unixdomain() socket (do not use a seek option then).
3164  
3165  
3166 label(EXAMPLE_OPTION_SETSID)
3167 label(EXAMPLE_OPTION_CTTY)
3168 mancommand(\.LP)
3169 mancommand(\.nf)
3170 mancommand(\fB(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
3171 socat - EXEC:'ssh -l user server',pty,setsid,ctty\fP)
3172 mancommand(\.fi)
3173  
3174 htmlcommand(<dt><code><strong>(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |</strong><br>
3175 <strong>socat - EXEC:'ssh -l user server',pty,setsid,ctty</strong></code><dd>)
3176  
3177 link(EXEC)(ADDRESS_EXEC)'utes an ssh session to server. Uses a link(pty)(OPTION_PTY) for communication between socat() and
3178 ssh, makes it ssh's controlling tty (link(ctty)(OPTION_CTTY)),
3179 and makes this pty the owner of
3180 a new process group (link(setsid)(OPTION_SETSID)), so ssh accepts the password from socat().
3181  
3182  
3183 label(EXAMPLE_ADDRESS_OPEN)
3184 label(EXAMPLE_OPTION_CREAT)
3185 label(EXAMPLE_OPTION_APPEND)
3186 mancommand(\.LP)
3187 mancommand(\.nf)
3188 mancommand(\fBsocat -u TCP4-LISTEN:3334,reuseaddr,fork \\
3189 OPEN:/tmp/in.log,creat,append\fP)
3190 mancommand(\.fi)
3191  
3192 htmlcommand(<dt><code><strong>socat -u TCP4-LISTEN:3334,reuseaddr,fork \</strong><br>
3193 <strong>OPEN:/tmp/in.log,creat,append</strong></code><dd>)
3194  
3195 implements a simple network based message collector.
3196 For each client connecting to port 3334, a new child process is generated (option link(fork)(OPTION_FORK)).
3197 All data sent by the clients are link(append)(OPTION_APPEND)'ed to the file /tmp/in.log.
3198 If the file does not exist, socat() link(creat)(OPTION_O_CREAT)'s it.
3199 Option link(reuseaddr)(OPTION_REUSEADDR) allows immediate restart of the server
3200 process.
3201  
3202 COMMENT(
3203 dit(bf(tt(socat TCP4-LISTEN:3335,reuseaddr,fork OPEN:/tmp/motd,rdonly)))
3204  
3205 implements a simple network based motd server.
3206 For each client connecting to port 3335, a new child process is generated
3207 (option link(fork)(OPTION_FORK)).
3208 The contents of the file /tmp/motd is sent to each client.
3209 Messages sent by clients result in an error due to option link(rdonly)(OPTION_RDONLY).
3210 Option link(reuseaddr)(OPTION_REUSEADDR) allows immediate restart of the server
3211 process.
3212 )
3213 COMMENT(
3214 dit(bf(tt(socat - TCP4-LISTEN:8080,mtudiscover=0,rcvbuf=2048)))
3215  
3216 changes some socket parameters to confuse active OS fingerprinting methods.
3217 link(mtudiscover)(OPTION_MTUDISCOVER)=0 sets the DF (don'ft fragment flag) in
3218 the IP packets to 0 and link(rcvbuf)(OPTION_RCVBUF) changes the initial TCP
3219 window size.
3220 )
3221  
3222 label(EXAMPLE_OPTION_NOECHO)
3223 dit(bf(tt(socat READLINE,noecho='[Pp]assword:' EXEC:'ftp ftp.server.com',pty,setsid,ctty)))
3224  
3225 wraps a command line history (link(READLINE)(ADDRESS_READLINE)) around the link(EXEC)(ADDRESS_EXEC)'uted ftp client utility.
3226 This allows editing and reuse of FTP commands for relatively comfortable
3227 browsing through the ftp directory hierarchy. The password is echoed!
3228 link(pty)(OPTION_PTY) is required to have ftp issue a prompt.
3229 Nevertheless, there may occur some confusion with the password and FTP
3230 prompts.
3231  
3232  
3233 label(EXAMPLE_ADDRESS_PTY)
3234 label(EXAMPLE_OPTION_SYMBOLIC_LINK)
3235 label(EXAMPLE_OPTION_WAIT_SLAVE)
3236 label(EXAMPLE_OPTION_NONBLOCK)
3237 mancommand(\.LP)
3238 mancommand(\.nf)
3239 mancommand(\fBsocat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \\\bf)
3240 mancommand(\fBEXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"\fP)
3241 mancommand(\.fi)
3242  
3243 htmlcommand(<dt><code><strong>socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \</strong><br>
3244 <strong>EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"'</strong></code><dd>)
3245  
3246 generates a pseudo terminal
3247 device (link(PTY)(ADDRESS_PTY)) on the client that can be reached under the
3248 symbolic link(link)(OPTION_SYMBOLIC_LINK) file($HOME/dev/vmodem0).
3249 An application that expects a serial line or modem
3250 can be configured to use file($HOME/dev/vmodem0); its traffic will be directed
3251 to a modemserver via ssh where another socat() instance links it to
3252 file(/dev/ttyS0).
3253  
3254  
3255 mancommand(\.LP)
3256 mancommand(\.nf)
3257 mancommand(\fBsocat TCP4-LISTEN:2022,reuseaddr,fork \\
3258 PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass\fP)
3259 mancommand(\.fi)
3260  
3261 htmlcommand(<dt><code><strong>socat TCP4-LISTEN:2022,reuseaddr,fork \</strong><br>
3262 <strong>PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass</strong></code><dd>)
3263  
3264 starts a forwarder that accepts connections on port 2022, and directs them
3265 through the link(proxy)(ADDRESS_PROXY_CONNECT) daemon listening on port 3128
3266 (link(proxyport)(OPTION_PROXYPORT)) on host proxy, using the
3267 CONNECT method, where they are authenticated as "user" with "pass" (link(proxyauth)(OPTION_PROXY_AUTHORIZATION)). The proxy
3268 should establish connections to host www.domain.org on port 22 then.
3269  
3270  
3271 label(EXAMPLE_ADDRESS_OPENSSL_CONNECT)
3272 dit(bf(tt(socat - SSL:server:4443,cafile=server.crt,cert=client.pem)))
3273  
3274 is an OpenSSL client that tries to establish a secure connection to an SSL
3275 server. Option link(cafile)(OPTION_OPENSSL_CAFILE) specifies a file that
3276 contains trust certificates: we trust the server only when it presents one of
3277 these certificates and proofs that it owns the related private key.
3278 Otherwise the connection is terminated.
3279 With link(cert)(OPTION_OPENSSL_CERTIFICATE) a file containing the client certificate
3280 and the associated private key is specified. This is required in case the
3281 server wishes a client authentication; many Internet servers do not.nl()
3282 The first address ('-') can be replaced by almost any other socat() address.
3283  
3284  
3285 label(EXAMPLE_ADDRESS_OPENSSL_LISTEN)
3286 dit(bf(tt(socat SSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE)))
3287  
3288 is an OpenSSL server that accepts TCP connections, presents the certificate
3289 from the file server.pem and forces the client to present a certificate that is
3290 verified against cafile.crt.nl()
3291 The second address ('PIPE') can be replaced by almost any other socat
3292 address.nl()
3293 For instructions on generating and distributing OpenSSL keys and certificates
3294 see the additional socat() docu tt(socat-openssl.txt).
3295  
3296  
3297 dit(bf(tt(echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000)))
3298  
3299 creates a 100GB sparse file; this requires a file system type that
3300 supports this (ext2, ext3, reiserfs, jfs; not minix, vfat). The operation of
3301 writing 1 byte might take long (reiserfs: some minutes; ext2: "no" time), and
3302 the resulting file can consume some disk space with just its inodes (reiserfs:
3303 2MB; ext2: 16KB).
3304  
3305  
3306 dit(bf(tt(socat tcp-l:7777,reuseaddr,fork system:'filan -i 0 -s >&2',nofork)))
3307  
3308 listens for incoming TCP connections on port 7777. For each accepted
3309 connection, invokes a shell. This shell has its stdin and stdout directly
3310 connected to the TCP socket (link(nofork)(OPTION_NOFORK)). The shell starts filan and lets it print the socket addresses to
3311 stderr (your terminal window).
3312  
3313  
3314 dit(bf(tt(echo -e "\0\14\0\0\c" |socat -u - file:/usr/bin/squid.exe,seek=0x00074420)))
3315  
3316 functions as primitive binary editor: it writes the 4 bytes 000 014 000 000 to
3317 the executable /usr/bin/squid at offset 0x00074420 (this is a real world patch
3318 to make the squid executable from Cygwin run under Windows, actual per May 2004).
3319  
3320  
3321 dit(bf(tt(socat - tcp:www.blackhat.org:31337,readbytes=1000)))
3322  
3323 connects to an unknown service and prevents being flooded.
3324  
3325  
3326 label(EXAMPLE_END_CLOSE)
3327 dit(bf(tt(socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork)))
3328  
3329 merges data arriving from different TCP streams on port 8888 to just one stream
3330 to target:9999. The link(end-close)(OPTION_END_CLOSE) option prevents the child
3331 processes forked off by the second address from terminating the shared
3332 connection to 9999 (close\(2) just unlinks the inode which stays active as long
3333 as the parent process lives; shutdown\(2) would actively terminate the
3334 connection).
3335  
3336  
3337 label(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT)
3338 dit(bf(tt(socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broadcast,range=192.168.1.0/24)))
3339  
3340 sends a broadcast to the network 192.168.1.0/24 and receives the replies of the
3341 timeservers there. Ignores NTP packets from hosts outside this network.
3342  
3343  
3344 label(EXAMPLE_ADDRESS_GENERIC_CLIENT)
3345 dit(bf(tt(socat - SOCKET-DATAGRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,setsockopt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000)))
3346  
3347 is semantically equivalent to the link(previous
3348 example)(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT), but all parameters are
3349 specified in generic form. the value 6 of setsockopt-int is the Linux value for
3350 tt(SO_BROADCAST).
3351  
3352  
3353 label(EXAMPLE_ADDRESS_IP4_BROADCAST_CLIENT)
3354 dit(bf(tt(socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8)))
3355  
3356 sends a broadcast to the local network\(s) using protocol 44. Accepts replies
3357 from the private address range only.
3358  
3359  
3360 label(EXAMPLE_ADDRESS_UDP4_MULTICAST)
3361 dit(bf(tt(socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-membership=224.255.0.1:eth0)))
3362  
3363 transfers data from stdin to the specified multicast address using UDP. Both
3364 local and remote ports are 6666. Tells the interface eth0 to also accept
3365 multicast packets of the given group. Multiple hosts on the local network can
3366 run this command, so all data sent by any of the hosts will be received
3367 by all the other ones. Note that there are many possible reasons for failure,
3368 including IP-filters, routing issues, wrong interface selection by the
3369 operating system, bridges, or a badly configured switch.
3370  
3371  
3372 label(EXAMPLE_ADDRESS_TUN)
3373 dit(bf(tt(socat TCP:host2:4443 TUN:192.168.255.1/24,up)))
3374  
3375 establishes one side of a virtual (but not private!) network with host2 where a
3376 similar process might run, with UDP-L and tun address 192.168.255.2. They can
3377 reach each other using the addresses 192.168.255.1 and 192.168.255.2. Note that
3378 streaming eg. via TCP or SSL does not guarantee to retain packet boundaries and
3379 may thus cause packet loss.
3380  
3381  
3382 label(EXAMPLE_INTERFACE)
3383 dit(bf(tt(socat PTY,link=/var/run/ppp,rawer INTERFACE:hdlc0)))
3384  
3385 circumvents the problem that pppd requires a serial device and thus might not
3386 be able to work on a synchronous line that is represented by a network device.
3387 socat() creates a PTY to make pppd happy, binds to the network
3388 link(interface)(ADDRESS_INTERFACE) tt(hdlc0), and can transfer data between
3389 both devices. Use pppd on device tt(/var/run/ppp) then.
3390  
3391  
3392 label(EXAMPLE_HTTPECHO)
3393 dit(bf(tt(socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:"echo -e \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate: \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient: \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e \"\\\"\\\n\\\"\"")))
3394  
3395 creates a simple HTTP echo server: each HTTP client that connects gets a valid
3396 HTTP reply that contains information about the client address and port as it is
3397 seen by the server host, the host address (which might vary on multihomed
3398 servers), and the original client request.
3399  
3400  
3401 label(EXAMPLE_ANCILLARY)
3402 dit(bf(tt(socat -d -d -%UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pktinfo,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl SYSTEM:'export; sleep 1' |grep SOCAT)))
3403  
3404 waits for an incoming UDP packet on port 9999 and prints the environment
3405 variables provided by socat. On BSD based systems you have to replace
3406 link(tt(ip-pktinfo))(OPTION_IP_PKTINFO) with link(tt(ip-recvdstaddr))(OPTION_IP_RECVDSTADDR),link(tt(ip-recvif))(OPTION_IP_RECVIF). Especially interesting is
3407 SOCAT_IP_DSTADDR: it contains the target address of the packet which may be a
3408 unicast, multicast, or broadcast address.
3409  
3410  
3411 label(EXAMPLE_SCTP_OPENSSL_IP6)
3412 dit(bf(tt(socat 'SCTP6-L:8888,reuseaddr,fork' '^SSL-L,fork,cert=testsrv.pem,verify=0|SYSTEM:export')))
3413  
3414 dit(bf(tt(socat - 'SSL,verify=0|SCTP6:ip6hostname:8888')))
3415  
3416 here two processes on different hosts communicate using openssl over SCTP on
3417 IPv6.
3418  
3419 dit(bf(tt()))
3420  
3421  
3422  
3423 enddit()
3424  
3425  
3426 label(DIAGNOSTICS)
3427 manpagediagnostics()
3428  
3429 Socat() uses a logging mechanism that allows to filter messages by severity. The
3430 severities provided are more or less compatible to the appropriate syslog
3431 priority. With one or up to four occurrences of the -d command line option, the
3432 lowest priority of messages that are issued can be selected. Each message
3433 contains a single uppercase character specifying the messages severity (one of
3434 F, E, W, N, I, or D)
3435  
3436 description(
3437 dit(FATAL:) Conditions that require unconditional and immediate program termination.
3438 dit(ERROR:) Conditions that prevent proper program processing. Usually the
3439 program is terminated (see link(option -s)(option_s)).
3440 dit(WARNING:) Something did not function correctly or is in a state where
3441 correct further processing cannot be guaranteed, but might be possible.
3442 dit(NOTICE:) Interesting actions of the program, e.g. for supervising socat() in some kind of server mode.
3443 dit(INFO:) Description of what the program does, and maybe why it
3444 happens. Allows to monitor the lifecycles of file descriptors.
3445 dit(DEBUG:) Description of how the program works, all system or library calls and their results.
3446 )
3447  
3448 Log messages can be written to stderr, to a file, or to syslog.
3449  
3450 On exit, socat() gives status 0 if it terminated due to EOF or inactivity
3451 timeout, with a positive value on error, and with a negative value on fatal
3452 error.
3453  
3454  
3455 label(FILES)
3456 manpagefiles()
3457  
3458 /usr/bin/socat nl()
3459 /usr/bin/filan nl()
3460 /usr/bin/procan
3461  
3462  
3463 label(ENVIRONMENT_VARIABLES)
3464 manpagesection(ENVIRONMENT VARIABLES)
3465  
3466 Input variables carry information from the environment to socat, output
3467 variables are set by socat() for use in executed scripts and programs.
3468  
3469 In the output variables beginning with "SOCAT" this prefix is actually replaced
3470 by the upper case name of the executable or the value of option
3471 link(-lp)(option_lp).
3472  
3473 startdit()
3474 label(ENV_SOCAT_DEFAULT_LISTEN_IP)
3475 dit(bf(SOCAT_DEFAULT_LISTEN_IP) (input)) (Values 4 or 6) Sets the IP version to
3476 be used for listen, recv, and recvfrom addresses if no
3477 link(pf)(OPTION_PROTOCOL_FAMILY) (protocol-family) option is given. Is
3478 overridden by socat() options link(-4)(option_4) or link(-6)(option_6).
3479  
3480 dit(bf(SOCAT_PREFERRED_RESOLVE_IP) (input)) (Values 0, 4, or 6) Sets the IP
3481 version to
3482 be used when resolving target host names when version is not specified by
3483 address type, option link(pf)(OPTION_PROTOCOL_FAMILY) (protocol-family), or
3484 address format. If name resolution does not return a matching entry, the first
3485 result (with differing IP version) is taken. With value 0, socat() always selects
3486 the first record and its IP version.
3487  
3488 dit(bf(SOCAT_MAIN_WAIT) (input)) Specifies the time (seconds) to sleep the
3489 socat() process immediately after start. Useful for debugging.
3490  
3491 dit(bf(SOCAT_FORK_WAIT) (input)) Specifies the time (seconds) to sleep the
3492 parent and child processes after successful fork\(). Useful for debugging.
3493  
3494 dit(bf(SOCAT_VERSION) (output)) Socat() sets this variable to its version string,
3495 e.g. tt("1.7.0.0") for released versions or e.g. tt("1.6.0.1+envvar") for
3496 temporary versions; can be used in scripts invoked by socat.
3497  
3498 dit(bf(SOCAT_PID) (output)) Socat() sets this variable to its process id. In case
3499 of link(fork)(OPTION_FORK) address option, SOCAT_PID gets the child processes
3500 id. Forking for link(exec)(ADDRESS_EXEC) and link(system)(ADDRESS_SYSTEM) does
3501 not change SOCAT_PID.
3502  
3503 dit(bf(SOCAT_PPID) (output)) Socat() sets this variable to its process id. In
3504 case of link(fork)(OPTION_FORK), SOCAT_PPID keeps the pid of the master process.
3505  
3506 dit(bf(SOCAT_PEERADDR) (output)) With passive socket addresses (all LISTEN and
3507 RECVFROM addresses), this variable is set to a string describing the peers
3508 socket address. Port information is not included.
3509  
3510 dit(bf(SOCAT_PEERPORT) (output)) With appropriate passive socket addresses
3511 (TCP, UDP, and SCTP - LISTEN and RECVFROM), this variable is set to a string containing the
3512 number of the peer port.
3513  
3514 dit(bf(SOCAT_SOCKADDR) (output)) With all LISTEN addresses, this variable is
3515 set to a string describing the local socket address. Port information is not
3516 included link(example)(EXAMPLE_HTTPECHO)
3517  
3518 dit(bf(SOCAT_SOCKPORT) (output)) With link(TCP-LISTEN)(ADDRESS_TCP_LISTEN),
3519 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), and
3520 link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN) addresses, this variable is set to the
3521 local port.
3522  
3523 dit(bf(SOCAT_TIMESTAMP) (output)) With all RECVFROM addresses where address
3524 option link(so-timestamp)(OPTION_SO_TIMESTAMP) is applied, socat() sets this
3525 variable to the resulting timestamp.
3526  
3527 dit(bf(SOCAT_IP_OPTIONS) (output)) With all IPv4 based RECVFROM addresses where
3528 address option link(ip-recvopts)(OPTION_IP_RECVOPTS) is applied, socat() fills
3529 this variable with the IP options of the received packet.
3530  
3531 dit(bf(SOCAT_IP_DSTADDR) (output)) With all IPv4 based RECVFROM addresses where
3532 address option link(ip-recvdstaddr)(OPTION_IP_RECVDSTADDR) (BSD) or
3533 link(ip-pktinfo)(OPTION_IP_PKTINFO) (other platforms) is applied, socat() sets
3534 this variable to the destination address of the received packet. This is
3535 particularly useful to identify broadcast and multicast addressed packets.
3536  
3537 dit(bf(SOCAT_IP_IF) (output)) With all IPv4 based RECVFROM addresses where
3538 address option link(ip-recvif)(OPTION_IP_RECVIF) (BSD) or
3539 link(ip-pktinfo)(OPTION_IP_PKTINFO) (other platforms) is applied, socat() sets
3540 this variable to the name of the interface where the packet was received.
3541  
3542 dit(bf(SOCAT_IP_LOCADDR) (output)) With all IPv4 based RECVFROM
3543 addresses where address option link(ip-pktinfo)(OPTION_IP_PKTINFO) is applied,
3544 socat() sets this variable to the address of the interface where the packet was
3545 received.
3546  
3547 dit(bf(SOCAT_IP_TOS) (output)) With all IPv4 based RECVFROM addresses where
3548 address option link(ip-recvtos)(OPTION_IP_RECVTOS) is applied, socat() sets this
3549 variable to the TOS (type of service) of the received packet.
3550  
3551 dit(bf(SOCAT_IP_TTL) (output)) With all IPv4 based RECVFROM addresses where
3552 address option link(ip-recvttl)(OPTION_IP_RECVTTL) is applied, socat() sets this
3553 variable to the TTL (time to live) of the received packet.
3554  
3555 dit(bf(SOCAT_IPV6_HOPLIMIT) (output)) With all IPv6 based RECVFROM addresses
3556 where address option link(ipv6-recvhoplimit)(OPTION_IPV6_RECVHOPLIMIT) is
3557 applied, socat() sets this variable to the hoplimit value of the received packet.
3558  
3559 dit(bf(SOCAT_IPV6_DSTADDR) (output)) With all IPv6 based RECVFROM
3560 addresses where address option link(ipv6-recvpktinfo)(OPTION_IPV6_RECVPKTINFO)
3561 is applied, socat() sets this variable to the destination address of the received
3562 packet.
3563  
3564 dit(bf(SOCAT_IPV6_TCLASS) (output)) With all IPv6 based RECVFROM addresses
3565 where address option link(ipv6-recvtclass)(OPTION_IPV6_RECVTCLASS) is applied,
3566 socat() sets this variable to the transfer class of the received packet.
3567  
3568 dit(bf(SOCAT_OPENSSL_X509_ISSUER) (output)) Issuer field from peer certificate
3569  
3570 dit(bf(SOCAT_OPENSSL_X509_SUBJECT) (output)) Subject field from peer certificate
3571  
3572 dit(bf(SOCAT_OPENSSL_X509_COMMONNAME) (output)) commonName entries from peer certificates subject. Multiple values are separated by " // ".
3573  
3574 dit(bf(SOCAT_OPENSSL_X509_*) (output)) all other entries from peer certificates subject
3575  
3576 dit(bf(SOCAT_OPENSSL_X509V3_DNS) (output)) DNS entries from peer certificates extensions - subjectAltName field. Multiple values are separated by " // ".
3577  
3578 dit(bf(HOSTNAME) (input)) Is used to determine the hostname for logging (see
3579 link(-lh)(option_lh)).
3580  
3581 dit(bf(LOGNAME) (input)) Is used as name for the socks client user name if no
3582 link(socksuser)(OPTION_SOCKSUSER) is given.nl()
3583 With options link(su)(OPTION_SUBSTUSER) and
3584 link(su-d)(OPTION_SUBSTUSER_DELAYED), LOGNAME is set to the given user name.
3585  
3586 dit(bf(USER) (input)) Is used as name for the socks client user name if no
3587 link(socksuser)(OPTION_SOCKSUSER) is given and LOGNAME is empty.nl()
3588 With options link(su)(OPTION_SUBSTUSER) and
3589 link(su-d)(OPTION_SUBSTUSER_DELAYED), USER is set to the given user name.
3590  
3591 dit(bf(SHELL) (output))
3592 With options link(su)(OPTION_SUBSTUSER) and
3593 link(su-d)(OPTION_SUBSTUSER_DELAYED), SHELL is set to the login shell of the
3594 given user.
3595  
3596 dit(bf(PATH) (output))
3597 Can be set with option link(path)(OPTION_PATH) for link(exec)(ADDRESS_EXEC) and
3598 link(system)(ADDRESS_SYSTEM) addresses.
3599  
3600 dit(bf(HOME) (output))
3601 With options link(su)(OPTION_SUBSTUSER) and
3602 link(su-d)(OPTION_SUBSTUSER_DELAYED), HOME is set to the home directory of the
3603 given user.
3604  
3605 enddit()
3606  
3607 label(CREDITS)
3608 manpagesection(CREDITS)
3609  
3610 The work of the following groups and organizations was invaluable for this
3611 project:
3612  
3613 The em(FSF) (GNU, lurl(http://www.fsf.org/) project
3614 with their free and portable development software and
3615 lots of other useful tools and libraries.
3616  
3617 The em(Linux developers community) (lurl(http://www.linux.org/)) for providing a free, open source operating
3618 system.
3619  
3620 The em(Open Group) (lurl(http://www.unix-systems.org/)) for making their
3621 standard specifications available on the Internet for free.
3622  
3623  
3624 label(VERSION)
3625 manpagesection(VERSION)
3626  
3627 This man page describes version 2.0.0-b8 of socat().
3628  
3629  
3630 label(BUGS)
3631 manpagebugs()
3632  
3633 Addresses cannot be nested, so a single socat() process cannot, e.g., drive ssl
3634 over socks.
3635  
3636 Address option ftruncate without value uses default 1 instead of 0.
3637  
3638 Verbose modes (-x and/or -v) display line termination characters inconsistently
3639 when address options cr or crnl are used: They show the data em(after)
3640 conversion in either direction.
3641  
3642 The data transfer blocksize setting (-b) is ignored with address readline.
3643  
3644 Send bug reports to <socat@dest-unreach.org>
3645  
3646  
3647 label(SEEALSO)
3648 manpageseealso()
3649  
3650 COMMENT(procan\(1), filan\(1), )
3651 nc\(1), netcat6\(1), sock\(1), rinetd\(8), cage\(1), socks.conf\(5),
3652 openssl\(1), stunnel\(8), pty\(1), rlwrap\(1), setsid\(1)
3653  
3654 Socat() home page lurl(http://www.dest-unreach.org/socat/)
3655  
3656 label(AUTHOR)
3657 manpageauthor()
3658  
3659 Gerhard Rieger <rieger@dest-unreach.org>