Good to see SRFI 170 get some serious mindshare before it's frozen:

> From: Lassi Kortela <xxxxxx@lassi.io>
> Date: Friday, July 31, 2020 5:55 AM
>
> The section 3.2 title is "I/O", perhaps to mirror the scsh manual. I/O
> is quite vague and generic: anything that touches the file system is
> basically I/O. In practice, section 3.2 only deals with file
> descriptors; could it be re-titled "File descriptors"?

The titles are precisely to mirror those in the scsh manual:

https://scsh.net/docu/html/man-Z-H-4.html#node_sec_3.2

And for that reason that bit of text should be kept.  But I see no
reason not to add a subtitle, either in the title, e.g. "I/O: File
Descriptors", or a subheading, or see below, it could also be covered
in a prefatory statement.

> The name `open-file` sounds very generic, high-level and convenient. But
> SRFI 170 `open-file` is pretty low-level, taking POSIX open() flags and
> returning a file descriptor. I suggest renaming it to `open-fdes` for
> symmetry with the `close-fdes` procedure that already exists.

Yeah, that's a good idea, especially to obtain symmetry as you note.

> The contraction "fdes" is somewhat non-standard, mainly used as a
> placeholder name in some manual pages. The common Unix shorthand is
> "fd". The generic cross-OS term is "file handle". Could we use either
> "fd" or "file-handle"? Here's how things would look:

I associate "file-handle" with the fopen et. al. set of buffered I/O
suite, but most importantly it's simply not the term used for raw I/O
(and as you later note, they're Windows specific words of art).  "fd"
is as you said common for the correct file descriptor words of art, is
for example the idiom used in the first 1978 edition of The C
Programming Language (I keep a copy so I can disrespect its chapter
on pointers and arrays, back then I used the Lions Notes to grok them).

I don't expect SRFI 170 users to know POSIX programming idioms, but
why not educate them?  As long as we have some prefatory text that
explains fdes or fd is shorthand for file descriptor, we could keep
the API as is, a compromise I now don't like:

> * open-fdes
> * close-fdes
> * port-fdes
> * fdes->textual-input-port
> * fdes->binary-input-port
> * fdes->textual-output-port
> * fdes->binary-output-port

Better, I agree, is fd:

> * open-fd
> * close-fd
> * port-fd
> * fd->textual-input-port
> * fd->binary-input-port
> * fd->textual-output-port
> * fd->binary-output-port

Or rather than handle, I tend to prefer spell things out, so maybe:

> * open-file-descriptor
> * close-file-descriptor
> * port-file-descriptor
> * file-descriptor->textual-input-port
> * file-descriptor->binary-input-port
> * file-descriptor->textual-output-port
> * file-descriptor->binary-output-port

> From: Lassi Kortela <xxxxxx@lassi.io>
> Date: Friday, July 31, 2020 6:00 AM
>
> Ugh, I just realized that a Windows program using a Linux emulation DLL
> can probably mix POSIX and WinAPI filesystem calls. So it can open a mix
> of POSIX file descriptors (C type: int) and Windows file handles (C
> type: HANDLE).
>
> So using `file-handle` in procedure names in a POSIX SRFI is not a good
> idea after all.
>
> Is `fd` too short?

Not for old hands at this, but thinking further, the fd idiom is so
pervasive it's would be good to introduce it to those new to POSIX in
the above mentioned prefatory statement.  That would be very useful
if they look at C code snippets to rewrite in Scheme.

- Harold