SNOBOL4IO(1)

💖 SNOBOL4IO(1) — the CSNOBOL4 Manual, file I/O edition 🎀

okay bestie, buckle up, this is snobol4io — SNOBOL4 file I/O — and it's lowkey one of the most unhinged-but-iconic pages in the whole manual. grab a snack. 🍓

---

✨ NAME ✨

snobol4io — SNOBOL4 file I/O 💅

---

🌸 DESCRIPTION 🌸

so back in the day, Macro SNOBOL4 was out here fully depending on FORTRAN libraries, unit numbers and FORMATs just to do input and output. not the vibe. CSNOBOL4 said "no thanks" and uses the C stdio(3) library instead — but the unit numbers (INTEGERs between 1 and 256) and record lengths are still chillin' embedded in the Macro SNOBOL4 code. periodt. 🫶

💫 I/O Associations

🚨 real talk: writing output on a closed unit generates a fatal “Output error”, see snobol4error(1). not a drill, bestie.

these variable/unit/file associations exist by default, no setup needed:

• INPUT — unit 5 — standard input (input)
• OUTPUT — unit 6 — standard output (output)
• TERMINAL — unit 7 — standard error (output)
• TERMINAL — unit 8 — /dev/tty (input)

🦋 Named files

you can hand input and output filenames to the INPUT() and OUTPUT() functions through an optional fourth argument. slay.

• filename - (hyphen) — gets interpreted as stdin on INPUT() and stdout on OUTPUT(). simple as that.
• sub-process I/O using PIPE and Pseudo-terminals — if the filename begins with a single vertical bar (|), the rest of it is used as a shell command whose stdin (in the case of OUTPUT()) or stdout (in the case of INPUT()) will be connected to the file variable via a pipe. and listen: if a pipe is opened by INPUT() in “update” mode, the connection will be bi-directional (on systems with socketpair and Unix-domain sockets). see below for how to associate a variable for I/O in both directions. 👀

if the filename begins with two vertical bars (||), the rest is used as a shell command executed with stdin, stdout and stderr attached to the slave side of a pseudo-terminal (pty), if the system C library contains the forkpty(3) routine. ptys are necessary when the program you're invoking can't be run without a “terminal” for I/O. see below on how to properly associate the I/O variable.

• magic paths /dev/stdin, /dev/stdout, and /dev/stderr — these refer to the current process standard input, standard output and standard error I/O streams respectively, regardless of whether those special filenames even exist on your system. it's giving magic fr fr ✨
• magic path /dev/fd/n — uses fdopen(3) to open a new I/O stream associated with file descriptor number n, regardless of whether the special device entries exist.
• magic paths /tcp/hostname/service, /udp/hostname/service and /tls/hostname/service — /tcp/hostname/service can be used to open a connection to a TCP server. /udp/hostname/service behaves similarly for UDP. /tls/hostname/service opens a TLS over TCP connection (NOTE! does not attempt to verify certificate unless the "verify" option is used, and even then does not handle SNI or SAN 😭). the path can be followed by a number of different slash separated options:
  • broadcast — Allow broadcast address (UDP only).
  • dontroute — Enables routing bypass for outgoing messages.
  • keepalive — Enables TCP connection keep alive messages.
  • nodelay — Send TCP data without waiting.
  • oobinline — Enables reception of out-of-band data in band.
  • priv — Bind local port number under 1024 (if allowed).
  • reuseaddr — Allow quick reuse of local addresses.
  • verify — Attempt to verify server TLS certificate.
• magic pathname /dev/tmpfile — opens an anonymous temporary file for reading and writing, see tmpfile(3).
• /dev/null and /dev/tty — on non-POSIX systems /dev/null and /dev/tty are magical, and refer to the null device, and the user's terminal/console, respectively.

---

💅 I/O Options 💅

originally, the third argument specified record length for INPUT(), or a FORTRAN FORMAT for OUTPUT(). iconic behaviour, honestly.

CSNOBOL4 interprets it as a string of single letter options, and commas are just ignored (we don't see them). some options effect only the I/O variable named in the first argument, others effect any variable associated with the unit number in the second argument. ok now the list, and yes, we're doing all of them. 💖

• digits — a span of digits will set the input record length for the named I/O variable. this controls the maximum string that will be returned for regular text I/O, and the number of bytes returned for binary I/O. record length is per-variable association; multiple variables may be associated with the same unit, but with different record lengths. the default record length for input is 1024. lines longer than the record length will be silently truncated 😭. since CSNOBOL4 2.2, record length is only honored for binary I/O, and all characters upto a newline (ASCII Line Feed) are interpreted as a single line.
• A — for OUTPUT() the unit will be opened for append access (and ignored by INPUT()). all writes will occur at the end of the file at the time of the write, regardless of the file position before the write. main character energy, always at the end 💅
• B — the unit will be opened for binary access. on input, newline characters have no special meaning; the number of bytes transferred depends on record length (see above). on output, no newline is appended.
• B — for terminal devices, all input from this unit will be done without special processing for line editing or EOF; the number of characters returned depends on the record length. characters which deliver signals (including interrupt, kill, and suspend) are still processed. units (with different fds) opened on the same terminal device operate independently; some can use binary mode, while others operate in text mode. ✨ (yes, B shows up twice. they're different vibes, we keep them both.)
• C — character at a time I/O. a synonym for B,1.
• E — set the "close on exec" flag for the underlying file descriptor. depends on support by the C library fopen(3) call for 'e' in the mode string for regular files. honored for sockets regardless, (but not on Windows).
• J — read and write compressed data in .xz format, using liblzma, as written by xz(1). if a digit 0 through 9 immediately follows the option, it will be interpreted as the compression level to use when writing. it's claimed that level zero is "sometimes faster than gzip -9 while compressing much better". the default compression level is 6, larger numbers will require more than 16MiB of memory to decompress, and are only useful only when compressing files bigger than 8 MiB (level 7), 16 MiB (level 8), and 32 MiB (level 9). matches the tar(1) command line option. added in CSNOBOL4 2.2.
• j — read and write compressed data in .bz2 format, using libbz2, as created by bzip2(1). if a digit 1 through 9 immediately follows the option, it will be interpreted as the compression level to use when writing. matches the tar(1) command line option. added in CSNOBOL4 2.2.
• K — if an input line is longer than the input record length, return the line in multiple reads (breaK up the line) instead of discarding the extra characters. added in CSNOBOL4 2.0. obsolete in CSNOBOL4 2.2. 🙈
• T — terminal mode. writes are performed “unbuffered” (see below), and no newline characters are added. on input newline characters are returned. terminal mode effects only the referenced unit, and does not require opening a new file descriptor (ie; by using a magic pathname): OUTPUT(.TT, 8, "T", "-"). terminal mode is useful for outputting prompts in interactive programs.
• Q — quiet mode. turns off input echo on terminals. effects only input on this file descriptor. 🤫
• U — update mode. the unit is opened for both input and output. example of associating a variable for I/O in both directions:

unit = IO_FINDUNIT()
INPUT(.name, unit, 'U', 'filepath')
OUTPUT(.name, unit)

useful situations for this when filepath is /dev/fd/n where n is a file descriptor number returned by SERV_LISTEN(), or filepath specifies a pipe (|command) or pseudo-terminal (||command) paths.

the above sequence is also useful with when combined with fixed record length, binary mode and the SET() function for I/O to preexisting files. performing OUTPUT() first will create a regular file if it does not exist, but will also truncate a preexisting file! 💀

• W — unbuffered mode. each output variable assignment causes an immediate I/O transfer to occur by direct read(1) or write(1) system calls, rather than collecting the data in a buffer for efficiency.
• X — open fails if file exists (meaningless for /dev/fd/n). depends on support by the C library fopen(3) call for 'x' in the mode string. added in CSNOBOL4 2.1 where it was ignored for sockets. in CSNOBOL4 2.2 applies to sockets, and means don't allow local socket address reuse.
• Z — reserved for .Z (compress(1)) style compression?! 🎀 (yes the question mark is canon, we love a mystery)
• z — read and write compressed data in .gz format using zlib(3), as created by gzip(1). if a digit 0 through 9 immediately follows the option, it will be interpreted as the compression level to use when writing. matches the tar(1) command line option. added in CSNOBOL4 2.2.

---

🌈 Other I/O extensions 🌈

• SERV_LISTEN(), SET(), SSET() — see snobol4func(1).

---

🧚 I/O Layers 🧚

the Macro SNOBOL4 and POSIX I/O architectures have subtleties which interact, and bestie we are explaining them here so you don't have to find out the hard way:

🎀 Variable association

input and output is done by reading or writing variables associated with a unit number for I/O.

input (maximum) record lengths are associated each variable association! (yes, that's the emphasis. it matters. 💅)

🎀 Unit number

multiple variables can be associated with the same unit number using the INPUT() and OUTPUT() functions.

each unit number refers to a stdio(3) stream (except on broken systems like Windows, where socket handles are incompatible with file handles, and all network I/O is performed “unbuffered”). 💀

sequential named files can be associated with an I/O unit when the -r option is given on the command line! REWIND() should return to to after the program END label!

🎀 “Standard I/O” Stream

snobol4(1) performs MOST I/O through “Standard Input/Output” streams. multiple units can be associated with the same stdio stream (FILE struct) using magic pathnames (“-” and /dev/std{in,out,err}). buffering is performed by the stdio layer. ✨

🎀 Operating System file descriptor

more than one stdio stream can be associated with the same O/S “fd” (by opening magic pathname /dev/fd/n).

each POSIX “fd” has a file position pointer, changed by reading, writing and the REWIND(), SET() and SSET() functions.

---

ok that's the first chunk, and there's more coming so don't go anywhere 🫶✨

Normally terminal device "special files" have one set of mode settings, but CSNOBOL4 associates (saves and restores) different terminal settings — echo and the number of characters returned on read — based on fd numbers. So like, each fd gets its own lil outfit 💅

---

🌈 Operating System open file object 🌈

More than one "fd" slot can be associated with the same "open file" object, either in multiple forks, or by dup(2) of the same fd. This is often the case for stdin, stdout and stderr. They're literally sharing one vibe 🫶

Open file objects have flags which effect all associated fds, including input, output and append modes. So touch one, you touch them all, no cap 😭

🦋 Operating System named file 🦋

Independent opens of the same named "regular" file will have different open file objects, and thus have independent access modes and file positions. Bestie they are not the same, they just look alike ✨

Terminal devices normally have one set of "line discipline" mode settings, but CSNOBOL4 maintains different settings for each file descriptor (see above). Iconic behaviour fr fr 💖

---

💀 BUGS 💀

This page was cut and pasted from various parts of the original snobol4(1) man page, and still needs review and cleanup. Not me exposing myself like this 🙈

All extensions should be annotated with the version they appeared in (and what other implementations they're compatible or inspired by). Like, receipts, please 🧾

Record lengths.

Unit numbers.

Okay so those last two are literally just sitting there with no explanation, and I'm keeping them exactly as they are because that's what the page says. Do not come for me, come for the man page 😭

---

👀 SEE ALSO 👀

• snobol4(1)
• snobol4ezio(3)

---

and that's the whole page, bestie!! 💖✨🎀

This one's from CSNOBOL4B, version 2.3.1, dated March 31, 2022, and it's the SNOBOL4IO(1) girlie 🦋