Page 1 of 1

REQS_MaxChars - wrong documentation?

Posted: Mon Sep 25, 2017 6:59 pm
by softwarefailure
I think the autodoc on REQS_MaxChars is wrong. It says:
Maximum number of characters in string gadget. Must not be larger than size of REQS_Buffer - 1. Defaults to 127.
In reality, however, REQS_MaxChars seems to require the buffer size of REQS_Buffer and not the buffer size of REQS_Buffer minus 1. So if I want the user to be able to enter 10 characters, I need to pass 11 to REQS_MaxChars. I guess the default is also 128 instead of the documented 127, i.e. 127 characters and a terminating null byte.

Re: REQS_MaxChars - wrong documentation?

Posted: Mon Sep 25, 2017 11:56 pm
by xenic
softwarefailure wrote:I think the autodoc on REQS_MaxChars is wrong. It says:
Maximum number of characters in string gadget. Must not be larger than size of REQS_Buffer - 1. Defaults to 127.
In reality, however, REQS_MaxChars seems to require the buffer size of REQS_Buffer and not the buffer size of REQS_Buffer minus 1. So if I want the user to be able to enter 10 characters, I need to pass 11 to REQS_MaxChars. I guess the default is also 128 instead of the documented 127, i.e. 127 characters and a terminating null byte.
I don't see the problem. If you set REQS_MaxChars to 11 then you need to set your buffer size to 12 or larger. OS4 is subject to change in future versions so it's better to abide by the rule and have the extra byte in the buffer than to risk future failure of your program.

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 8:44 am
by salass00
If REQS_MaxChars has worked like it does now since the beginning and it's not just a recent bug then the more appropriate action would be to correct the documentation. Less chance of breaking existing programs that way.

BTW the autodoc entry for STRINGA_MaxChars doesn't mention at all whether the nul-terminator should be included in the value or not (it should). This should be clarified as well given that the tag name implies otherwise.

I'll fix both entries later today if someone else doesn't do it first.

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 4:13 pm
by softwarefailure
xenic wrote: I don't see the problem.
The problem is that the documentation is wrong. Of course it would be utter non-sense to change the behaviour of REQS_MaxChars and break binary compatibility but the documentation needs to be fixed because what it currently states is wrong.

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 5:23 pm
by broadblues
softwarefailure wrote:I think the autodoc on REQS_MaxChars is wrong. It says:
Maximum number of characters in string gadget. Must not be larger than size of REQS_Buffer - 1. Defaults to 127.
In reality, however, REQS_MaxChars seems to require the buffer size of REQS_Buffer and not the buffer size of REQS_Buffer minus 1. So if I want the user to be able to enter 10 characters, I need to pass 11 to REQS_MaxChars. I guess the default is also 128 instead of the documented 127, i.e. 127 characters and a terminating null byte.
No the REQS_MaxChars must as stated be no more than RQS_Buffer -1 this is not an error. The extra byte is for the terminating NULL as you might expect.

The confusion comes from the string.gadget needing 1 extra character to be able to enter a full length string, so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 6:02 pm
by softwarefailure
broadblues wrote:so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )
Why must the buffer be 12 bytes to enter 10 chars? Does it write two null terminators?

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 7:27 pm
by broadblues
softwarefailure wrote:
broadblues wrote:so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )
Why must the buffer be 12 bytes to enter 10 chars? Does it write two null terminators?
Because REQS_MaxChars must be a maximum of REQS_Buffer - 1

But the string gadget needs STRINGA_MaxChars to be 1 more than you need to enter (perhaps for the null or perhaps for a working byte) which might be argued to be bug, but is established behaviour for a long time.

Thus to ensure compatabilty there needs to be chars + 2 in the buffer

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 7:47 pm
by xenic
softwarefailure wrote:
broadblues wrote:so if you need to enter 10 chars then REQS_MaxChars must be 11 (and the buffer must be 12 )
Why must the buffer be 12 bytes to enter 10 chars? Does it write two null terminators?
Since '\0' is a char, the char count is 11 and the printable char count is 10.

Since we don't have access to the source code, we don't know what it does. Judging what it does based on "what works" could be wrong. I wrote a simple test program and set REQS_Maxchars to 12 and set REQS_Buffer size to 8. The program didn't bring up a Grim Reaper and didn't crash. However, I'm not going to assume that it should be done that way.

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 9:08 pm
by salass00
broadblues wrote: Because REQS_MaxChars must be a maximum of REQS_Buffer - 1
That's what the autodoc said but it isn't true for any version of "requester.class" that is tagged in the SVN. Most likely the behaviour was changed very early on and the autodoc entry was simply not updated to reflect this.

I've fixed both STRINGA_MaxChars and REQS_MaxChars entries to make it clear that space for the nul-terminator needs to be included in the character count.

Re: REQS_MaxChars - wrong documentation?

Posted: Tue Sep 26, 2017 9:37 pm
by softwarefailure
I've fixed both STRINGA_MaxChars and REQS_MaxChars entries to make it clear that space for the nul-terminator needs to be included in the character count.
In other words, both xenic and broadblues are wrong, just to make that clear again in case people dig up this thread later. No need to make things more complex than they are. It's a simple error in the doc, nothing to write home about.