From a6f101248ee409e1b952fa9560f409127701e9c7 Mon Sep 17 00:00:00 2001 From: Steve Bennett Date: Thu, 13 Apr 2023 09:18:57 +1000 Subject: docs: Add documentation for -noclose flag To open, socket and accept Also document aio getfd Signed-off-by: Steve Bennett --- jim_tcl.txt | 74 +++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 47 insertions(+), 27 deletions(-) diff --git a/jim_tcl.txt b/jim_tcl.txt index ba288ff..d337fb6 100644 --- a/jim_tcl.txt +++ b/jim_tcl.txt @@ -59,6 +59,7 @@ Changes since 0.82 3. `stacktrace` is now a builtin command 4. The stack trace on error now includes the full stack trace, not just back to where it was caught 5. Improvements with `aio`, related to eventloop and buffering. Add `aio timeout`. +6. `socket` , `open` and `aio accept` now support '-noclose' Changes between 0.81 and 0.82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3507,7 +3508,7 @@ with last option being used. open ~~~~ -+*open* 'fileName ?access?'+ ++*open* 'fileName *?-noclose?* ?access?'+ +*open* '|command-pipeline ?access?'+ @@ -3516,6 +3517,9 @@ that may be used in future invocations of commands like `read`, `puts`, and `close`. +'fileName'+ gives the name of the file to open. +If +'-noclose'+ is given, the returned handle is not automatically +closed for child proceses. + The +'access'+ argument indicates the way in which the file is to be accessed. It may have any of the following values: @@ -3689,6 +3693,8 @@ Creates a pair of `aio` channels and returns the handles as a list: +{read write $r readable ... ---- +Note that if '+-noclose+' is desired, use `socket -noclose pipe` instead. + pwd ~~~ +*pwd*+ @@ -4893,11 +4899,13 @@ over `aio read` and `aio puts`. aio ~~~ -+$handle *accept* ?addrvar?+:: ++$handle *accept ?-noclose?* ?addrvar?+:: Server socket only: Accept a connection and return a stream channel. If +'addrvar'+ is specified, the address of the connected client is - stored in the named variable in the form 'addr:port' for IP sockets or - 'path' for Unix domain sockets. See `socket` for details. + stored in the named variable in the form 'addr:port' for IP sockets + or 'path' for Unix domain sockets. See `socket` for details. + If +'-noclose'+ is given, the returned handle is not automatically + closed for child proceses. See `socket` for details. +$handle *buffering none|line|full*+:: Sets the output buffering mode of the stream channel. +'none'+ means @@ -4957,6 +4965,9 @@ aio the file is not a newline character, then `gets` behaves as if there were an additional newline character at the end of the file. ++$handle *getfd*+:: + Returns the underlying file descriptor. On Unix platforms this is a small integer. + +$handle *isatty*+:: Returns 1 if the channel is a tty device. @@ -5229,55 +5240,55 @@ to prevent infinite errors. (A time event handler is always removed after execut socket ~~~~~~ -Various socket types may be created. +Various socket types may be created as follows. -+*socket unix* 'path'+:: ++*socket ?-noclose? unix* 'path'+:: A unix domain socket client connected to 'path' - 'filename' returns +'path'+ + 'filename' returns +'path'+ -+*socket unix.server* 'path'+:: ++*socket ?-noclose? unix.server* 'path'+:: A unix domain socket server listening on 'path' - 'filename' returns +'path'+ + 'filename' returns +'path'+ -+*socket unix.dgram* '?path?'+:: ++*socket ?-noclose? unix.dgram* '?path?'+:: A unix domain socket datagram client, optionally connected to 'path' - 'filename' returns +'path'+ if provided or "dgram" if not + 'filename' returns +'path'+ if provided or "dgram" if not -+*socket unix.dgram.server* 'path'+:: ++*socket ?-noclose? unix.dgram.server* 'path'+:: A unix domain socket datagram server server listening on 'path' - 'filename' returns +'path'+ + 'filename' returns +'path'+ -+*socket ?-async? ?-ipv6? stream* 'addr:port'+:: ++*socket ?-noclose? ?-async? ?-ipv6? stream* 'addr:port'+:: A TCP socket client. (See the forms for +'addr'+ below) - 'filename' returns +'addr:port'+ + 'filename' returns +'addr:port'+ -+*socket ?-async? ?-ipv6? stream.server* '?addr:?port'+:: ++*socket ?-noclose? ?-async? ?-ipv6? stream.server* '?addr:?port'+:: A TCP socket server (+'addr'+ defaults to +0.0.0.0+ for IPv4 or +[::]+ for IPv6). - 'filename' returns +'addr:port'+ + 'filename' returns +'addr:port'+ -+*socket ?-async? ?-ipv6? dgram* ?'addr:port'?+:: ++*socket ?-noclose? ?-async? ?-ipv6? dgram* ?'addr:port'?+:: A UDP socket client. If the address is not specified, the client socket will be unbound and 'sendto' must be used to indicated the destination. - 'filename' returns +'addr:port'+ if provided or "dgram" if not + 'filename' returns +'addr:port'+ if provided or "dgram" if not -+*socket ?-async? ?-ipv6? dgram.server* 'addr:port'+:: ++*socket ?-noclose? ?-async? ?-ipv6? dgram.server* 'addr:port'+:: A UDP socket server. - 'filename' returns +'addr:port'+ + 'filename' returns +'addr:port'+ -+*socket pipe*+:: ++*socket ?-noclose? pipe*+:: A synonym for `pipe` - 'filename' returns "pipe" + 'filename' returns "pipe" -+*socket pair*+:: ++*socket ?-noclose? pair*+:: A socketpair (see socketpair(2)). Like `pipe`, this command returns a list of two channels: {s1 s2}. These channels are both readable and writable. - 'filename' returns "pair" + 'filename' returns "pair" -+*socket pty*+:: ++*socket ?-noclose? pty*+:: A pseudo-tty pair (see openpty(3)). Like `pipe`, this command returns a list of two channels: {primary replica}. These channels are both readable and writable. - 'filename' for both handles returns the replica filename. + 'filename' for both handles returns the replica filename. This command creates a socket connected (client) or bound (server) to the given address. @@ -5360,6 +5371,15 @@ will succeed if connected or fail if connect failed. Typical usage is as follows vwait done ---- +If '+-noclose+' is specified, the socket is not automatically closed for child proceses. e.g. + +---- + lassign [socket -noclose pipe] r w + # This file descriptor will be open in the child process + # with the file descriptors passed on the command line + exec subcommand [$r getfd] [$w getfd] +---- + syslog ~~~~~~ +*syslog* '?options? ?priority? message'+ -- cgit v1.1