From 167b17afd33ac6f26b934d20678b73fc3a35aec7 Mon Sep 17 00:00:00 2001 From: "jan.nijtmans" Date: Wed, 12 Jun 2024 09:59:13 +0000 Subject: Add METHOD headers to documentation. Other doc cleanup, backported from 8.7/9.0 --- doc/SaveResult.3 | 1 + doc/SetResult.3 | 1 + doc/chan.n | 126 +++++++++++++++++++++++++++++++++---------------------- 3 files changed, 79 insertions(+), 49 deletions(-) diff --git a/doc/SaveResult.3 b/doc/SaveResult.3 index 918941e..fe532b6 100644 --- a/doc/SaveResult.3 +++ b/doc/SaveResult.3 @@ -27,6 +27,7 @@ int \fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR) .sp \fBTcl_DiscardResult\fR(\fIsavedPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_InterpState savedPtr .AP Tcl_Interp *interp in diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 4a68aac..9c6d47c 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -37,6 +37,7 @@ const char * \fBTcl_AppendElement\fR(\fIinterp, element\fR) .sp \fBTcl_FreeResult\fR(\fIinterp\fR) +.fi .SH ARGUMENTS .AS Tcl_FreeProc sourceInterp out .AP Tcl_Interp *interp out diff --git a/doc/chan.n b/doc/chan.n index 77e9326..53f8123 100644 --- a/doc/chan.n +++ b/doc/chan.n @@ -21,6 +21,7 @@ channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR which correspond to the process's standard input, output and error streams respectively). \fIOption\fR indicates what to do with the channel; any unique abbreviation for \fIoption\fR is acceptable. Valid options are: +.\" METHOD: blocked .TP \fBchan blocked \fIchannelId\fR . @@ -30,6 +31,7 @@ process to block, and returns 1 if that was the case. It returns 0 otherwise. Note that this only ever returns 1 when the channel has been configured to be non-blocking; all Tcl channels have blocking turned on by default. +.\" METHOD: close .TP \fBchan close \fIchannelId\fR ?\fIdirection\fR? . @@ -90,6 +92,7 @@ system resource, which can change how other processes or systems respond to the Tcl program. .VE 8.6 .RE +.\" METHOD: configure .TP \fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... . @@ -112,8 +115,10 @@ for the options supported by that specific type of channel. For example, see the manual entry for the \fBsocket\fR command for additional options for sockets, and the \fBopen\fR command for additional options for serial devices. +.RE +.\" OPTION: -blocking .TP -\fB\-blocking\fR \fIboolean\fR +\fB\-blocking\fI boolean\fR . The \fB\-blocking\fR option determines whether I/O operations on the channel can cause the process to block indefinitely. The value of the @@ -125,8 +130,9 @@ documentation for those commands for details. For non-blocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR command). +.\" OPTION: -buffering .TP -\fB\-buffering\fR \fInewValue\fR +\fB\-buffering\fI newValue\fR . If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output until its internal buffer is full or until the \fBchan flush\fR @@ -139,13 +145,15 @@ channels that connect to terminal-like devices; for these channels the initial setting is \fBline\fR. Additionally, \fBstdin\fR and \fBstdout\fR are initially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR. +.\" OPTION: -buffersize .TP -\fB\-buffersize\fR \fInewSize\fR +\fB\-buffersize\fI newSize\fR . -\fINewvalue\fR must be an integer; its value is used to set the size +\fInewSize\fR must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store -input or output. \fINewvalue\fR must be a number of no more than one +input or output. \fInewSize\fR must be a number of no more than one million, allowing buffers of up to one million bytes in size. +.\" OPTION: -encoding .TP \fB\-encoding\fR \fIname\fR . @@ -174,6 +182,7 @@ The default encoding for newly opened channels is the same platform- and locale-dependent system encoding used for interfacing with the operating system, as returned by \fBencoding system\fR. .RE +.\" OPTION: -eofchar .TP \fB\-eofchar\fR \fIchar\fR .TP @@ -197,10 +206,11 @@ for writing. The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f; attempting to set \fB\-eofchar\fR to a value outside of this range will generate an error. +.\" OPTION: -translation .TP -\fB\-translation\fR \fImode\fR +\fB\-translation\fI translation\fR .TP -\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR +\fB\-translation\fR \fB{\fIinTranslation outTranslation\fB}\fR . In Tcl scripts the end of a line is always represented using a single newline character (\en). However, in actual files and devices the end @@ -226,9 +236,7 @@ you can specify a single value that will apply to both reading and writing. When querying the translation mode of a read-write channel, a two-element list will always be returned. The following values are currently supported: -.TP -\fBauto\fR -. +.IP \fBauto\fR As the input translation mode, \fBauto\fR treats any of newline (\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by a newline (\fBcrlf\fR) as the end of line representation. The end of @@ -239,26 +247,24 @@ all platforms Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, and for the various flavors of Windows it chooses \fBcrlf\fR. The default setting for \fB\-translation\fR is \fBauto\fR for both input and output. -.TP -\fBbinary\fR -. -No end-of-line translations are performed. This is nearly identical -to \fBlf\fR mode, except that in addition \fBbinary\fR mode also sets -the end-of-file character to the empty string (which disables it) and -sets the encoding to \fBbinary\fR (which disables encoding filtering). -See the description of \fB\-eofchar\fR and \fB\-encoding\fR for more -information. -.TP -\fBcr\fR -. +.IP \fBbinary\fR +Like \fBlf\fR, no end-of-line translation is performed, but in addition, sets +\fB\-eofchar\fR to the empty string to disable it, and sets \fB\-encoding\fR +to \fBiso8859-1\fR. With this one setting, a channel is fully configured +for binary input and output: Each byte read from the channel +becomes the Unicode character having the same value as that byte, and each +character written to the channel becomes a single byte in the output. This +makes it possible to work seamlessly with binary data as long as each character +in the data remains in the range of 0 to 255 so that there is no distinction +between binary data and text. For example, A JPEG image can be read from a +such a channel, manipulated, and then written back to such a channel. +.IP \fBcr\fR The end of a line in the underlying file or device is represented by a single carriage return character. As the input translation mode, \fBcr\fR mode converts carriage returns to newline characters. As the output translation mode, \fBcr\fR mode translates newline characters to carriage returns. -.TP -\fBcrlf\fR -. +.IP \fBcrlf\fR The end of a line in the underlying file or device is represented by a carriage return character followed by a linefeed character. As the input translation mode, \fBcrlf\fR mode converts @@ -266,15 +272,13 @@ carriage-return-linefeed sequences to newline characters. As the output translation mode, \fBcrlf\fR mode translates newline characters to carriage-return-linefeed sequences. This mode is typically used on Windows platforms and for network connections. -.TP -\fBlf\fR -. +.IP \fBlf\fR The end of a line in the underlying file or device is represented by a single newline (linefeed) character. In this mode no translations occur during either input or output. This mode is typically used on UNIX platforms. .RE -.RE +.\" METHOD: copy .TP \fBchan copy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR? . @@ -346,6 +350,7 @@ incoming bytes are valid UTF-8 characters and convert them according to the output encoding. The behaviour of the system for bytes which are not valid UTF-8 characters is undefined in this case. .RE +.\" METHOD: create .TP \fBchan create \fImode cmdPrefix\fR . @@ -364,7 +369,7 @@ reading, writing, or both. It has to be a list containing any of the strings .QW \fBread\fR or -.QW \fBwrite\fR . +.QW \fBwrite\fR , The list must have at least one element, as a channel you can neither write to nor read from makes no sense. The handler command for the new channel must support the chosen @@ -412,12 +417,14 @@ interpreters. While it arranges for the execution of arbitrary Tcl code the system also makes sure that the code is always executed within the safe interpreter. .RE +.\" METHOD: eof .TP \fBchan eof \fIchannelId\fR . Test whether the last input operation on the channel called \fIchannelId\fR failed because the end of the data stream was reached, returning 1 if end-of-file was reached, and 0 otherwise. +.\" METHOD: event .TP \fBchan event \fIchannelId event\fR ?\fIscript\fR? . @@ -444,7 +451,8 @@ while waiting for the data to arrive. If an application invokes no input data available, the process will block; until the input data arrives, it will not be able to service other events, so it will appear to the user to -.QW "freeze up" . +.QW "freeze up" +\&. With \fBchan event\fR, the process can tell when data is present and only invoke \fBchan gets\fR or \fBchan read\fR when they will not block. @@ -486,6 +494,7 @@ to report the error. In addition, the file event handler is deleted if it ever returns an error; this is done in order to prevent infinite loops due to buggy handlers. .RE +.\" METHOD: flush .TP \fBchan flush \fIchannelId\fR . @@ -500,6 +509,7 @@ buffered output has been flushed; the remainder will be flushed in the background as fast as the underlying file or device is able to absorb it. .RE +.\" METHOD: gets .TP \fBchan gets \fIchannelId\fR ?\fIvarName\fR? . @@ -521,12 +531,14 @@ distinguished from an empty line using the \fBchan eof\fR command, and the partial-line-but-non-blocking case can be distinguished with the \fBchan blocked\fR command. .RE +.\" METHOD: names .TP \fBchan names\fR ?\fIpattern\fR? . Produces a list of all channel names. If \fIpattern\fR is specified, only those channel names that match it (according to the rules of \fBstring match\fR) will be returned. +.\" METHOD: pending .TP \fBchan pending \fImode channelId\fR . @@ -538,8 +550,10 @@ callback to impose application-specific limits on input line lengths to avoid a potential denial-of-service attack where a hostile user crafts an extremely long line that exceeds the available memory to buffer it). Returns -1 if the channel was not opened for the mode in question. +.\" METHOD: pipe .TP \fBchan pipe\fR +. .VS 8.6 Creates a standalone pipe whose read- and write-side channels are returned as a 2-element list, the first element being the read side and @@ -560,10 +574,12 @@ differences, but the details of what exactly gets written when are not. This is most likely to show up when using pipelines for testing; care should be taken to ensure that deadlocks do not occur and that potential short reads are allowed for. -.RE .VE 8.6 +.RE +.\" METHOD: pop .TP \fBchan pop \fIchannelId\fR +. .VS 8.6 Removes the topmost transformation from the channel \fIchannelId\fR, if there is any. If there are no transformations added to \fIchannelId\fR, this is @@ -571,6 +587,7 @@ equivalent to \fBchan close\fR of that channel. The result is normally the empty string, but can be an error in some situations (i.e. where the underlying system stream is closed and that results in an error). .VE 8.6 +.\" METHOD: postevent .TP \fBchan postevent \fIchannelId eventSpec\fR . @@ -607,8 +624,10 @@ where the event is posted from a safe interpreter and listened for by a trusted interpreter. \fBChan event\fR handlers are \fIalways\fR executed in the interpreter that set them up. .RE +.\" METHOD: push .TP \fBchan push \fIchannelId cmdPrefix\fR +. .VS 8.6 Adds a new transformation on top of the channel \fIchannelId\fR. The \fIcmdPrefix\fR argument describes a list of one or more words which represent @@ -619,6 +638,7 @@ is important to make sure that the transformation is capable of supporting the channel mode that it is used with or this can make the channel neither readable nor writable. .VE 8.6 +.\" METHOD: puts .TP \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR . @@ -658,6 +678,7 @@ used in an event-driven fashion with the \fBchan event\fR command (do not invoke \fBchan puts\fR unless you have recently been notified via a file event that the channel is ready for more output data). .RE +.\" METHOD: read .TP \fBchan read \fIchannelId\fR ?\fInumChars\fR? .TP @@ -712,6 +733,7 @@ end-of-file character, see \fBchan configure -eofchar\fR. If there no end-of-file character has been configured for the channel, then \fBchan read\fR will block forever. .RE +.\" METHOD: seek .TP \fBchan seek \fIchannelId offset\fR ?\fIorigin\fR? . @@ -720,20 +742,14 @@ the channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to \fIorigin\fR. \fIOffset\fR must be an integer (which may be negative) and \fIorigin\fR must be one of the following: .RS -.TP 10 -\fBstart\fR -. +.IP \fBstart\fR The new access position will be \fIoffset\fR bytes from the start of the underlying file or device. -.TP 10 -\fBcurrent\fR -. +.IP \fBcurrent\fR The new access position will be \fIoffset\fR bytes from the current access position; a negative \fIoffset\fR moves the access position backwards in the underlying file or device. -.TP 10 -\fBend\fR -. +.IP \fBend\fR The new access position will be \fIoffset\fR bytes from the end of the file or device. A negative \fIoffset\fR places the access position before the end of file, and a positive \fIoffset\fR places the access @@ -751,6 +767,7 @@ Note that \fIoffset\fR values are byte offsets, not character offsets. Both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, not characters, unlike \fBchan read\fR. .RE +.\" METHOD: tell .TP \fBchan tell \fIchannelId\fR . @@ -760,6 +777,7 @@ value returned is a byte offset that can be passed to \fBchan seek\fR in order to set the channel to a particular position. Note that this value is in terms of bytes, not characters like \fBchan read\fR. The value returned is -1 for channels that do not support seeking. +.\" METHOD: truncate .TP \fBchan truncate \fIchannelId\fR ?\fIlength\fR? . @@ -769,10 +787,18 @@ offset within the underlying data stream if \fIlength\fR is omitted). The channel is flushed before truncation. . .SH EXAMPLES +.SS "SIMPLE CHANNEL OPERATION EXAMPLES" +.PP +Instruct Tcl to always send output to \fBstdout\fR immediately, +whether or not it is to a terminal: +.PP +.CS +\fBfconfigure\fR stdout -buffering none +.CE .PP -This opens a file using a known encoding (CP1252, a very common encoding -on Windows), searches for a string, rewrites that part, and truncates the -file after a further two lines. +In the following example a file is opened using the encoding CP1252, which is +common on Windows, searches for a string, rewrites that part, and truncates the +file two lines later. .PP .CS set f [open somefile.txt r+] @@ -782,7 +808,7 @@ set offset 0 \fI# Search for string "FOOBAR" in the file\fR while {[\fBchan gets\fR $f line] >= 0} { set idx [string first FOOBAR $line] - if {$idx > -1} { + if {$idx >= 0} { \fI# Found it; rewrite line\fR \fBchan seek\fR $f [expr {$offset + $idx}] @@ -803,8 +829,8 @@ while {[\fBchan gets\fR $f line] >= 0} { \fBchan close\fR $f .CE .PP -A network server that does echoing of its input line-by-line without -preventing servicing of other connections at the same time. +A network server that echoes its input line-by-line without +preventing servicing of other connections at the same time: .PP .CS # This is a very simple logger... @@ -842,9 +868,11 @@ vwait forever .SH "SEE ALSO" close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n), fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n), -socket(n), tell(n), refchan(n), transchan(n) +socket(n), tell(n), refchan(n), transchan(n), +Tcl_StandardChannels(3) .SH KEYWORDS -channel, input, output, events, offset +blocking, channel, end of file, events, input, non-blocking, +offset, output, readable, seek, stdio, tell, writable '\" Local Variables: '\" mode: nroff '\" End: -- cgit v0.12