Is there a good place to lookup the various error codes returned by tcl commands?

In the try command manual there's an example:

try {
set f [open /some/file/name w]
} trap {POSIX EISDIR} {} {
puts "failed to open /some/file/name: it's a directory"
} trap {POSIX ENOENT} {} {
puts "failed to open /some/file/name: it doesn't exist"
}

How did the writer of this example know about these two error cases since they are not documented in the manual under either try or open.

Also, are POSIX error codes system independent?

Am 16.08.24 um 20:28 schrieb et99:
> Is there a good place to lookup the various error codes returned by tcl
> commands?
>
> In the try command manual there's an example:
>
> try {
>     set f [open /some/file/name w]
> } trap {POSIX EISDIR} {} {
>     puts "failed to open /some/file/name: it's a directory"
> } trap {POSIX ENOENT} {} {
>     puts "failed to open /some/file/name: it doesn't exist"
> }
>
> How did the writer of this example know about these two error cases
> since they are not documented in the manual under either try or open.
>
> Also, are POSIX error codes system independent?
>
>

Hello;
maybe this helps:

https://www.tcl.tk/man/tcl8.6/TclCmd/tclvars.htm#M12

source code tcl 8.6
../tcl8.6.14/win/tclWinError.c
/.tcl8.6.14/generic/tclPosixStr.c

https://en.wikipedia.org/wiki/Errno.h

On 8/16/2024 9:45 PM, greg wrote:
> Am 16.08.24 um 20:28 schrieb et99:
>> Is there a good place to lookup the various error codes returned by tcl commands?
>>
>> In the try command manual there's an example:
>>
>> try {
>>      set f [open /some/file/name w]
>> } trap {POSIX EISDIR} {} {
>>      puts "failed to open /some/file/name: it's a directory"
>> } trap {POSIX ENOENT} {} {
>>      puts "failed to open /some/file/name: it doesn't exist"
>> }
>>
>> How did the writer of this example know about these two error cases since they are not documented in the manual under either try or open.
>>
>> Also, are POSIX error codes system independent?
>>
>>
>
> Hello;
> maybe this helps:
>
> https://www.tcl.tk/man/tcl8.6/TclCmd/tclvars.htm#M12
>
> source code tcl 8.6
> ./tcl8.6.14/win/tclWinError.c
> /.tcl8.6.14/generic/tclPosixStr.c
>
>
> https://en.wikipedia.org/wiki/Errno.h

Thanks for the links.

I was afraid this was probably the only way to get the codes.

I think this could make a useful TIP - to add an error section to all command man pages as is done in the linux man pages.

If I were 30 years younger, with the inherent time and energy, I might have volunteered to do this, since it is obviously a tedious and perhaps thankless job.

I guess I will just stick to using my if-catch-template and not try to differentiate the particular errors. Besides, only I ever use my programs anymore :)

-e

Am 17.08.2024 um 09:09 schrieb et99:
> On 8/16/2024 9:45 PM, greg wrote:
>> Am 16.08.24 um 20:28 schrieb et99:
>>> Is there a good place to lookup the various error codes returned by
>>> tcl commands?
>>>
>>> In the try command manual there's an example:
>>>
>>> try {
>>>      set f [open /some/file/name w]
>>> } trap {POSIX EISDIR} {} {
>>>      puts "failed to open /some/file/name: it's a directory"
>>> } trap {POSIX ENOENT} {} {
>>>      puts "failed to open /some/file/name: it doesn't exist"
>>> }
>>>
>>> How did the writer of this example know about these two error cases
>>> since they are not documented in the manual under either try or open.
>>>
>>> Also, are POSIX error codes system independent?
>>>
>>>
>>
>> Hello;
>> maybe this helps:
>>
>> https://www.tcl.tk/man/tcl8.6/TclCmd/tclvars.htm#M12
>>
>> source code tcl 8.6
>> ./tcl8.6.14/win/tclWinError.c
>> /.tcl8.6.14/generic/tclPosixStr.c
>>
>>
>> https://en.wikipedia.org/wiki/Errno.h
>
>
> Thanks for the links.
>
> I was afraid this was probably the only way to get the codes.
>
> I think this could make a useful TIP - to add an error section to all
> command man pages as is done in the linux man pages.
>
> If I were 30 years younger, with the inherent time and energy, I might
> have volunteered to do this, since it is obviously a tedious and perhaps
> thankless job.
>
> I guess I will just stick to using my if-catch-template and not try to
> differentiate the particular errors. Besides, only I ever use my
> programs anymore :)

Thank you for the words and the initiative.
Reality is worse. We are on 3 platforms.
So, we try to get the same error code on all of them.
Errors come often from system calls. On Posix systems, they are just put
up to the script. On WIndows, Windows error codes are mapped to possix
error codes, which works more or less...

Remark that error codes are also available by catch.

The advantage of try is that you have a cleanup case, which is always
executed, even on error and on return.

so:

proc t {fn} {
try {
set f [open $fn]
set d [read $f]
return $d
} trap ...
} on ...
} finally {
if {[info exists f]} {close $f}
} }

Closes the file in any handling case. It is beautiful, that the finally
happens after the return command and the return still works.

This is a constructed example. But it might be handy.

Take care,
Harald

On 8/19/2024 1:01 AM, Harald Oehlmann wrote:
> Am 17.08.2024 um 09:09 schrieb et99:
>> On 8/16/2024 9:45 PM, greg wrote:
>>> Am 16.08.24 um 20:28 schrieb et99:
>>>> Is there a good place to lookup the various error codes returned by tcl commands?

...snip

> Thank you for the words and the initiative.
> Reality is worse. We are on 3 platforms.
> So, we try to get the same error code on all of them.
> Errors come often from system calls. On Posix systems, they are just put up to the script. On WIndows, Windows error codes are mapped to possix error codes, which works more or less...
>
> Remark that error codes are also available by catch.

I see the problem. However, many tcl command manual entries have sections describing differences between systems. If error codes are different, that would be an appropriate place to document that as well.

I was thinking about the leverage one would have if all the error codes were documented in one place. By them not being easy to find, I just take the lazy course and use catch and write out whatever error message the catch returns. If they were documented once, then (all) programmers would have an easier time.

>
> The advantage of try is that you have a cleanup case, which is always executed, even on error and on return.
>
> so:
>
> proc t {fn} {
> try {
> set f [open $fn]
> set d [read $f]
> return $d
> } trap ...
> } on ...
> } finally {
>     if {[info exists f]} {close $f}
> }
> }
>
> Closes the file in any handling case. It is beautiful, that the finally happens after the return command and the return still works.
>
> This is a constructed example. But it might be handy.

This finally behavior I had not known. It also seems quite remarkable to me since ordinarily once a return statement is executed, the stack frame would be expected to be popped and so that variable f would no longer be accessible. Clearly try must be doing something special if it can execute code after a return command.

I just re-read both return and try manual pages and I cannot find anywhere that mentions this behavior explicitly with a return command. Frankly, this seems like a good way to create a lurking bug.

It reminds me of the C code gotcha where a programmer added the andthis w/o realizing the scope of the if statement:

if(boolean)
dothis;
andthis;

-e

>This finally behavior I had not known. It also seems quite remarkable to me since ordinarily once a return statement is executed, the stack frame would be expected to be popped and so that variable f would no longer be accessible. Clearly try must be doing something special if it can execute code after a return command.

From the first paragraph of the try man page:

.... if the finally clause is present, the script it includes will be run and the result of the handler (or the body if no handler matched) is allowed to continue to propogate.

The "result of the body" is the result from the try script, not the finally script.

I'm kind of amazed it works too, but it is very nice that it does. My most common use for try {...} finally {...} is to close a file regardless of any errors after reading and maybe processing the contents inside the try script.

daveb

On 8/20/2024 10:08 PM, clt.to.davebr@dfgh.net wrote:

>
> I'm kind of amazed it works too, but it is very nice that it does. My most common use for try {...} finally {...} is to close a file regardless of any errors after reading and maybe processing the contents inside the try script.
>
> daveb
>
>
>

Well, I *finally* decided to read sections 11.2-3 in Ashok's great Tcl book and the text and examples there has cleared up everything for me.

That explains how the try command can execute the finally clause *after* the execution of the return command. It's because try gets to do whatever it wants with the return code of 2 that the return command itself returns.

-e