| 1 | '\" |
|---|
| 2 | '\" Copyright (c) 1998-1999 Scriptics Corporation |
|---|
| 3 | '\" |
|---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
|---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
|---|
| 6 | '\" |
|---|
| 7 | '\" RCS: @(#) $Id: Access.3,v 1.9 2004/10/07 14:44:31 dkf Exp $ |
|---|
| 8 | '\" |
|---|
| 9 | .so man.macros |
|---|
| 10 | .TH Tcl_Access 3 8.1 Tcl "Tcl Library Procedures" |
|---|
| 11 | .BS |
|---|
| 12 | .SH NAME |
|---|
| 13 | Tcl_Access, Tcl_Stat \- check file permissions and other attributes |
|---|
| 14 | .SH SYNOPSIS |
|---|
| 15 | .nf |
|---|
| 16 | \fB#include <tcl.h>\fR |
|---|
| 17 | .sp |
|---|
| 18 | int |
|---|
| 19 | \fBTcl_Access\fR(\fIpath\fR, \fImode\fR) |
|---|
| 20 | .sp |
|---|
| 21 | int |
|---|
| 22 | \fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR) |
|---|
| 23 | .SH ARGUMENTS |
|---|
| 24 | .AS "struct stat" *statPtr out |
|---|
| 25 | .AP char *path in |
|---|
| 26 | Native name of the file to check the attributes of. |
|---|
| 27 | .AP int mode in |
|---|
| 28 | Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. R_OK, |
|---|
| 29 | W_OK and X_OK request checking whether the file exists and has read, |
|---|
| 30 | write and execute permissions, respectively. F_OK just requests |
|---|
| 31 | checking for the existence of the file. |
|---|
| 32 | .AP "struct stat" *statPtr out |
|---|
| 33 | The structure that contains the result. |
|---|
| 34 | .BE |
|---|
| 35 | |
|---|
| 36 | .SH DESCRIPTION |
|---|
| 37 | .PP |
|---|
| 38 | As of Tcl 8.4, the object-based APIs \fBTcl_FSAccess\fR and |
|---|
| 39 | \fBTcl_FSStat\fR should be used in preference to \fBTcl_Access\fR and |
|---|
| 40 | \fBTcl_Stat\fR, wherever possible. |
|---|
| 41 | .PP |
|---|
| 42 | There are two reasons for calling \fBTcl_Access\fR and \fBTcl_Stat\fR |
|---|
| 43 | rather than calling system level functions \fBaccess\fR and \fBstat\fR |
|---|
| 44 | directly. First, the Windows implementation of both functions fixes |
|---|
| 45 | some bugs in the system level calls. Second, both \fBTcl_Access\fR |
|---|
| 46 | and \fBTcl_Stat\fR (as well as \fBTcl_OpenFileChannelProc\fR) hook |
|---|
| 47 | into a linked list of functions. This allows the possibility to reroute |
|---|
| 48 | file access to alternative media or access methods. |
|---|
| 49 | .PP |
|---|
| 50 | \fBTcl_Access\fR checks whether the process would be allowed to read, |
|---|
| 51 | write or test for existence of the file (or other file system object) |
|---|
| 52 | whose name is pathname. If pathname is a symbolic link on Unix, |
|---|
| 53 | then permissions of the file referred by this symbolic link are |
|---|
| 54 | tested. |
|---|
| 55 | .PP |
|---|
| 56 | On success (all requested permissions granted), zero is returned. On |
|---|
| 57 | error (at least one bit in mode asked for a permission that is denied, |
|---|
| 58 | or some other error occurred), -1 is returned. |
|---|
| 59 | .PP |
|---|
| 60 | \fBTcl_Stat\fR fills the stat structure \fIstatPtr\fR with information |
|---|
| 61 | about the specified file. You do not need any access rights to the |
|---|
| 62 | file to get this information but you need search rights to all |
|---|
| 63 | directories named in the path leading to the file. The stat structure |
|---|
| 64 | includes info regarding device, inode (always 0 on Windows), |
|---|
| 65 | privilege mode, nlink (always 1 on Windows), user id (always 0 on |
|---|
| 66 | Windows), group id (always 0 on Windows), rdev (same as device on |
|---|
| 67 | Windows), size, last access time, last modification time, and creation |
|---|
| 68 | time. |
|---|
| 69 | .PP |
|---|
| 70 | If \fIpath\fR exists, \fBTcl_Stat\fR returns 0 and the stat structure |
|---|
| 71 | is filled with data. Otherwise, -1 is returned, and no stat info is |
|---|
| 72 | given. |
|---|
| 73 | |
|---|
| 74 | .SH KEYWORDS |
|---|
| 75 | stat, access |
|---|
| 76 | |
|---|
