Documented here: https://pubs.opengroup.org/onlinepubs/009695399/functions/xsh_chap02_05.html#tag_02_05_01
This provides the best chance at read_raw() reading from the right
location and updating the file pointer as expected while avoiding
behaviour which is explicitly undefined by POSIX.

Reverted the SAFECOPY() NULL source-pointer magic "(null)" string thing as that caused a different Coverity issue. Explicitly check for NULL at the call-sites instead.

Reverted the SAFECOPY() NULL source-pointer magic "(null)" string thing as that caused a different Coverity issue. Explicitly check for NULL at the call-sites instead.

Hopefully not introducing any bugs in the process.

Hopefully not introducing any bugs in the process.

Doing so prevents extending the prototype.

Some (important) File methods did not support .ini files that used the !include directive because they were using the xpdev iniRead* API (which performs no "pre-processing") instead of xpdev iniGet*.

Impacted methods:
- iniGetValue()
- iniGetKeys()
- iniGetObject()

The other existing ini* methods already worked fine with nested (!include'd) .ini files. It's possible there's a slight performance penalty with the new implementation since the entire .ini file is always read for each operation and previously it was possible that only a few "lines" were read to find the key(s) of interest. However, since .ini files are not typically huge and the iniRead/file-stream method likely read large (e.g. 8-32K) blocks anyway (which is usually the entire .ini file) - I don't actually suspect any observable impact to performance.

This change was needed for the new ctrl/modopts.d support.

Added new method useful for debugging nested .ini files:
- iniReadAll()

If an .ini file is read by either the iniGetObject() or iniGetAllObjects() methods and contains a key with a blank value, that property would be created with an "undefined" value.

Both the iniGetObject() and iniGetAllObjects() methods now accept an additional Boolean argument (which defaults to false), to specify that "blanks" are acceptable. When the "blanks" argument is true, then keys with empty values in the .ini file are created as properties with empty string values (length of 0).

This is going to be useful for modopts.js to read potentially-blank strings from modopts.ini and differentiate between a blank string key and a missing key.

I'm fed-up with MSVC assertions in ctype functions (e.g. isdigit, isprint, isspace, etc.) when called with out-of-range (e.g. negative) values.

This problem only affects MSVC debug builds, but if you run them (like I do), these things are like little time bombs that can drive you crazy (knocking your board out of service).

The new macros names are bit more descriptive as well.

iniReadFile():
- enables the use of the !include directive in the read .in file
- reduces rewinds/re-reads of the .ini file, speeding up the total operation

I also removed the old crash dump comments from here.

documented (it says if the section is *undefined*, the root section is read)

iniGetAllObjects() to sort of "normalize" the key names into easily-useable
(and consistent) JavaScript property names.

JS numbers are double-precision floating points (doubles) and doubles cannot
be converted to unsigned integers uniformly across all architectures (e.g.
specifically on ARM, negative numbers would mostly get converted to 0U).

For details, see
https://www.embeddeduse.com/2013/08/25/casting-a-negative-float-to-an-unsigned-int/

Moved some dbprintf() lines around a bit.

If dup() fails, return NULL
If callog() fails, fclose() the new FILE*
No functional change (hopefully).

to TRUE meant the FILE* (created with fdopen) would never be closed. So we now
duplicate the file descriptor and get rid of the external flag, always closing
Files (FILE streams) upon File object finalize.
This fixes the resource leak leading to the eventual "Error 24 opening ..." in
the ircd.js when loaded via jsexec, on Windows. This error happened after
169 calls to load(true,...), because each background load creates 3 Files
(for stdin/out/err) and those FILE streams were never closed/freed, and
169 * 3 = 507, plus a few open files = 512, the maximum number of open file
streams in the Microsoft CRTL apparently. Thanks to Deuce for recognizing these
numbers as "magic" and pointing to the likely cause.

"4294967295 File closed"
"0000 File closed: /path/to/file"

if fdopen() failed, we'd close the file descriptor but leave it dangling with
a >= 0 value and then call close() again on it later in the function.

'maxlen' argument. E.g. passing 10 would result in a maximum read string length
of 9 characters.

was based on _finddata_t.attrib value while the value *written* was based on
struct stat.st_mode, and totally incompatible.
Just use the stat/chmod compatible value for both read and write (for all
OSes). If you need the old Windows-centric attribute values (e.g. to determine
"hidden" or "archive" attributes), use file_attrib() instead.

declaration

Use this in place of JS_GetPrivate() in native class methods that need the
class instance's private data pointer and will do bad things if that pointer
points to something other than what is expected. mcmlxxix (matt) discovered
that using Object.apply(), you can invoke class methods where the 'this'
instance is a different class. This would result in
"Internal Error: No Private Data." or a crash.
So now, gracefully detect this condition and report a meaningful error:
"'<class-name>' instance: No Private Data or Class Mismatch"

Also, important to note: if the method uses JS_THIS_OBJECT to get the JSObject*
to pass to JS_Get*Private, then it must do this *before* it calls JS_SET_RVAL.

From jsapi.h:
 * NB: there is an anti-dependency between JS_CALLEE and JS_SET_RVAL: native
 * methods that may inspect their callee must defer setting their return value
 * until after any such possible inspection. Otherwise the return value will be
 * inspected instead of the callee function object.

The js_crypt*.c files still need this treatment.

because the stdout FILE* is a different address in jsexec than it is in sbbs.dll
(where the actual File I/O operations occurred). Refactored by passing the
stdio file descriptor (and open mode) to js_CreateFileObject rather than the
FILE* and using fdopen() to get a FILE* associated with the descriptor.
stdout.write() now works, for example.

Also, the File() constructor will now properly complain if no filename
is passed.

- ini_key_len
- ini_key_prefix
- ini_section_separator
- ini_value_separator
- ini_bit_separator
- ini_literal_separator

    "Deprecated file open mode: 'e'"
If this is your script generating this warning, either remove the 'e' from
the File open() mode string (it had no effect anyway) or change to 'x' to
get the real/working exclusive-open functionality (added in v3.17).

simply ignored when converted to the underlying open mode passed to sopen().
Deprecate this flag and log a warning when it is detected as used in a script:
Deprecated open flag used: 'e'
Added 'x' (exclsuive-open) mode flag which:
1. was tested to work as intended
2. is consistent with the C11 standard for fopen() mode flags
3. won't cause existing scripts to suddenly break

unused functions).