close-input-port(3scm)

📦 version 0-unstable-2024-02, in nixpkgs unstable

💅 close-input-port, close-output-port — close a port

okay so real talk, this page is from the Scheme Programmer's Manual and it's literally about the two little procedures that hang up the phone on your ports. bestie, it's giving "small but essential." let's go 🎀

✨ NAME ✨

close-input-port, close-output-port — close a port, that's it, that's the whole vibe 🫶

📚 LIBRARY 📚

import these depending on which Scheme flavour you're living in, no cap:

(import (rnrs))                     ;R6RS
(import (rnrs io simple))           ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

🌸 SYNOPSIS 🌸

(close-input-port port)
(close-output-port port)

two procedures, one job each. iconic. ⭐

💖 DESCRIPTION 💖

So what they do is: they close the file associated with port, which makes the port completely incapable of delivering or accepting characters. like, the port is done, it's retired, it's on a beach somewhere 🏖️. And the cutest part? these routines have no effect if the file has already been closed — so you can't double-close and break stuff. very forgiving. we love her.

R6RS — if port is a custom port, then the closer procedure gets called before the port is really closed.

Also in R6RS: custom ports have a single closer procedure, so they do not compose well with only closing one direction. and R6RS doesn't explicitly say anything at all about closing only one direction. so like... it's a bit of a "figure it out bestie" situation 😭

R7RS — Scheme implementations may provide ports that are simultaneously input and output ports, such as sockets 🧦. and with those, close-input-port and close-output-port can be used to close the input and output sides independently. two sides, two goodbyes, fully separate. slay.

🦋 RETURN VALUES 🦋

returns unspecified values. nobody's asking for a receipt here, okay? 💅

🍓 EXAMPLES 🍓

look at her go:

(define p (open-output-file "hello.txt"))
(display "Hello, world\n" p)
(close-output-port p)

open, write, close. the holy trinity. ate. 🔥

🌈 APPLICATION USAGE 🌈

okay this part is important, listen up 👑: ports are often connected to some limited resource, like a file descriptor. so closing ports is genuinely important to avoid resource leaks — yes, leaks are real and they will find you. some implementations will garbage collect ports, but that is not required, so don't be out here relying on it like it's a promise. it is not a promise. 🫶

🧚 RATIONALE 🧚

in R6RS these procedures are part of the "simple I/O" library, which exists for compatibility with code written for R5RS and earlier reports. like a hand-me-down jacket but make it standards-compliant ✨

💜 COMPATIBILITY 💜

these procedures are provided for portability with code written for R5RS and earlier reports. old code, new home. we respect the elders. 🙈

💀 ERRORS 💀

this procedure can raise exceptions with the following condition types:

  • &assertion (R6RS) — the wrong number of arguments was passed, or an argument was outside its domain. wrong vibes, essentially.
R7RS — the assertions described above are errors. implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically 💀. yes, catastrophically. so maybe don't.

Also, it is an error to apply these procedures to a port which is not an input or output port, respectively. so don't hand close-input-port an output port and expect a happy ending, bestie. 😭

🔍 SEE ALSO 🔍

⭐ STANDARDS ⭐

R4RS, IEEE Scheme, R5RS, R6RS, R7RS — that's five whole standards. certified, notarized, stamped. 👑

🎀 AUTHORS 🎀

this page is part of the scheme-manpages project, and it includes materials from the RnRS documents. more info lives at https://github.com/schemedoc/manpages/. go say hi to the maintainers, they're doing the lord's work 🫶

🙈 BUGS 🙈

ngl it is often better to use call-with-port(3scm) or one of the related procedures. why? because they make it easier to ensure that a port is closed when an exception is raised. so like, the manual is lowkey telling you to use the fancier one. we listen to the manual. 💅

mwah 💋 that's a wrap on close-input-port(3scm) — dated 2021-02-28, close those ports, stay leak-free, and remember: the vibe is immaculate but the resource limits are real. bye bestie! 🦋✨

📦 where this page comes from