tcl/doc/Access.3

   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$
   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 in
  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