Tcl_CreateFileHandler(3)

✨ Tcl_CreateFileHandler — bestie, it's giving event-driven 💅 ✨

okay so this is the Tcl Library Procedures page for Tcl_CreateFileHandler and its partner in crime Tcl_DeleteFileHandler, and yes it is Unix only — like, don't come at me if you're on Windows, this vibe is not for you 🫶

---

🌸 NAME 🌸

Tcl_CreateFileHandler, Tcl_DeleteFileHandler — associate procedure callbacks with files or devices (Unix only) 🔥

---

🌈 SYNOPSIS 🌈

#include <tcl.h>

Tcl_CreateFileHandler(fd, mask, proc, clientData)

Tcl_DeleteFileHandler(fd)

---

🎀 ARGUMENTS 🎀

• int fd (in) — a Unix file descriptor for an open file or device. like the little number that points at your file, slay 💅
• int mask (in) — the conditions under which proc should be called: an OR-ed combination of TCL_READABLE, TCL_WRITABLE, and TCL_EXCEPTION. you can also set it to 0 to temporarily disable a handler, no cap ✨
• Tcl_FileProc *proc (in) — the procedure to invoke whenever the file or device indicated by file meets the conditions specified by mask. it's the main character that gets called 🫶
• void *clientData (in) — arbitrary one-word value to pass to proc. literally whatever you want, one word, that's it 🍓

---

💖 DESCRIPTION 💖

Tcl_CreateFileHandler arranges for proc to be invoked in the future whenever I/O becomes possible on a file, or when an exceptional condition exists for the file. the file is indicated by fd, and the conditions of interest are indicated by mask. for example, if mask is TCL_READABLE, proc will be called when the file is readable. so simple, so iconic ✨

the callback to proc is made by Tcl_DoOneEvent, so Tcl_CreateFileHandler is only useful in programs that dispatch events through Tcl_DoOneEvent or through Tcl commands such as vwait. iykyk — no event loop, no callback, periodt 💀

proc should have arguments and result that match the type Tcl_FileProc:

typedef void Tcl_FileProc(
        void *clientData,
        int mask);

the clientData parameter to proc is a copy of the clientData argument given to Tcl_CreateFileHandler when the callback was created. typically, clientData points to a data structure containing application-specific information about the file. mask is an integer mask indicating which of the requested conditions actually exists for the file; it will contain a subset of the bits in the mask argument to Tcl_CreateFileHandler. subset bestie, not the whole thing, keep up 💅

ok so here's the tea 🫖 — there may exist only one handler for a given file at a given time. if Tcl_CreateFileHandler is called when a handler already exists for fd, then the new callback replaces the information that was previously recorded. not merged, not queued, straight up replaced 😭

Tcl_DeleteFileHandler may be called to delete the file handler for fd; if no handler exists for the file given by fd then the procedure has no effect. it's a vibe, it's chill, nothing bad happens 🌸

the purpose of file handlers is to enable an application to respond to events while waiting for files to become ready for I/O. for this to work correctly, the application may need to use non-blocking I/O operations on the files for which handlers are declared. otherwise the application may block if it reads or writes too much data; while waiting for the I/O to complete the application will not be able to service other events. use Tcl_SetChannelOption with -blocking to set the channel into blocking or nonblocking mode as required. blocking is the enemy of the vibe, fr fr 🙈

note that these interfaces are only supported by the Unix implementation of the Tcl notifier. that's the whole rule. 🌈

---

🦋 SEE ALSO 🦋

• fileevent(n)
• Tcl_CreateTimerHandler(3)
• Tcl_DoWhenIdle(3)

---

⭐ KEYWORDS ⭐

callback, file, handler

---

and that's the whole page, bestie 💖 this one lives in the Tcl 8.0 era of the manual — Tcl_CreateFileHandler(3), Tcl Library Procedures, so go forth and handle your files, you absolute icon 👑 🎀