# TIP 603: Get 'stat' Information of Open Files
	Author:         Donal K. Fellows <donal.k.fellows@manchester.ac.uk>
	State:          Final
	Type:           Project
	Vote:           Done
	Created:        19-Jun-2021
	Post-History:
	Keywords:       Tcl, file
	Tcl-Version:    8.7
	Tcl-Branch:     tip-603
	Vote-Summary:	Accepted 5/1/1
	Votes-For:	AK, DKF, JN, KBK, SL
	Votes-Against:	KW
	Votes-Present:	FV
-----

# Abstract

This TIP proposes adding the ability to get information such as is produced by
`file stat` for an open file. This has security advantages.

# Rationale

With symbolic links and the ability to make substantial changes to a directory
after a file in it is opened, it is necessary to sometimes be able to
determine exact file information about a file that has already been opened.
This has distinct security advantages (once you have a file opened, nobody can
truly take it away from you as you have a lock on the inode or equivalent).
POSIX systems handle this with the `fstat()` system call, available on all
platforms Tcl supports except Windows.

However, on Windows the implementation of `file stat` (`NativeStat()` in
`tclWinFile.c`) works by opening the file and then using
`GetFileInformationByHandle()`. As we already have an open handle in the
situation we are looking to support, using it with that call should be
straight-forward.

# Specification

For at least file handles opened on conventional files, there will be an
additional _read-only_ option that can be retrieved with
`chan configure`: **-stat**. This will return a dictionary (same format as
[TIP #594](594.md) proposes returning) that contains the file information
determined by the `fstat()` or `GetFileInformationByHandle()` system call
(depending on platform) at the time that the call is performed. The option
will not be available for the standard file channel type if the file does not
have a native handle.

It will be undefined whether channels opened on other things will have that
option, but if they do and are defined by Tcl, they _must_ use the same format
of value. (Third-party channels are not so constrained.)

It will be the responsibility of the caller to flush channels prior to calling
if they believe that doing so will make a significant difference to the
results.

This entails no public C API changes.

# Other Options

I considered creating **chan stat** _channel_, but thought that that has the
disadvantage of requiring every channel type to consider adding the
functionality when it only really makes sense for files (and file-like things)
opened on the native filesystem. (For example, it makes no sense at all for
files stored in a mounted zip file.)

This option would require extending the channel API at the C level, and
consequently would be quite a bit more work.

# Copyright

This document is placed in public domain.
