Tcl_Access(3tcl)

💖 Tcl_Access — check file permissions & other attributes 💖

okay bestie so we're in the 3tcl manual, Tcl Library Procedures section, and today's main characters are Tcl_Access and Tcl_Stat. yes they're giving slightly retro, but they still eat. let's get into it 🫶

---

✨ NAME ✨

Tcl_Access, Tcl_Stat — check file permissions and other attributes

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_Access(path, mode)

int
Tcl_Stat(path, statPtr)

---

🎀 ARGUMENTS 🎀

• const char *path (in) — the native name of the file whose attributes we're checking. literally just the path, girl.
• int mode (in) — a mask made of one or more of R_OK, W_OK, X_OK and F_OK. so like: R_OK, W_OK and X_OK are asking "does this file exist and can I read / write / execute it?" respectively, and F_OK is just "does the file even exist tho".
• struct stat *statPtr (out) — the structure that holds the result. it gets filled in for you, she's an output param 💅

---

🦋 DESCRIPTION 🦋

so the object-based APIs Tcl_FSAccess and Tcl_FSStat should be used in preference to Tcl_Access and Tcl_Stat, wherever possible. like, if you can, use those ones. why? because those functions also support Tcl's virtual filesystem layer, and these two do not. no cap.

🌈 OBSOLETE FUNCTIONS 🌈

there are two reasons you might call Tcl_Access and Tcl_Stat instead of calling the system level functions access and stat directly:

1. the Windows implementation of both functions fixes some bugs in the system level calls. so on Windows, these are actually doing you a solid.
2. both Tcl_Access and Tcl_Stat (as well as Tcl_OpenFileChannelProc) hook into a linked list of functions. which means there's the possibility to reroute file access to alternative media or access methods. iconic, honestly.

---

Tcl_Access checks whether the process would be allowed to read, write or test for existence of the file (or other file system object) whose name is path. heads up: if path is a symbolic link on Unix, then the permissions of the file referred by this symbolic link are tested. (so it's following the link, not judging the link itself, iykyk)

on success (all requested permissions granted), zero is returned. 🎉 on error — meaning at least one bit in mode asked for a permission that is denied, or some other error occurred — -1 is returned. 😭

---

Tcl_Stat fills the stat structure statPtr with information about the specified file. plot twist: you do not need any access rights to the file to get this information, but you do need search rights to all directories named in the path leading to the file. so the vibes of the parent directories matter.

the stat structure includes info regarding:

• device
• inode (always 0 on Windows)
• privilege mode
• nlink (always 1 on Windows)
• user id (always 0 on Windows)
• group id (always 0 on Windows)
• rdev (same as device on Windows)
• size
• last access time
• last modification time
• creation time

if path exists, Tcl_Stat returns 0 and the stat structure is filled with data. otherwise, -1 is returned, and no stat info is given. 🙈

---

🔥 KEYWORDS 🔥

stat, access

---

💜 SEE ALSO 💜

Tcl_FSAccess(3tcl), Tcl_FSStat(3tcl)

---

okay that's the whole page, you're so welcome 💖 this was Tcl version 8.1, from the Tcl Library Procedures manual, and the page is Tcl_Access(3tcl). go forth and check those permissions, bestie — you got this 👑✨