[fortran, patch] Update *.texi: document ACCESS and CHMOD

[Tobias Burnus <burnus at net-b dot de>]

:ADDPATCH fortran:

Split off & updated from (unrelated) new_line patch.

ACCESS is indeed implemented in gfortran; someone (e.g.  I) should go
through the manual and PR19292 to see, which intrinsics are already
implemented and which are are still missing. I think both the bug and
the manual are outdated.

Tobias

2006-10-08
    * fortran/gfortran.texi: Add link to GFortran apps
    * fortran/intrinsic.texi: Updated documentation of ACCESS and CHMOD

Index: gfortran.texi
===================================================================
--- gfortran.texi	(Revision 117554)
+++ gfortran.texi	(Arbeitskopie)
@@ -161,7 +161,7 @@
 @item
 Read a user's program,
 stored in a file and containing instructions written
-in Fortran 77, Fortran 90 or Fortran 95.
+in Fortran 77, Fortran 90, Fortran 95 or Fortran 2003.
 This file contains @dfn{source code}.
 
 @item
@@ -404,7 +404,8 @@
 @uref{http://mysite.verizon.net/serveall/moene.pdf, the HIRLAM
 weather-forecasting code} and
 @uref{http://www.theochem.uwa.edu.au/tonto/, the Tonto quantum 
-chemistry package}.
+chemistry package}; see @url{http://gcc.gnu.org/wiki/GfortranApps} for an
+extended list.
 
 Among other things, the GNU Fortran compiler is intended as a replacement
 for G77.  At this point, nearly all programs that could be compiled with
Index: intrinsic.texi
===================================================================
--- intrinsic.texi	(Revision 117554)
+++ intrinsic.texi	(Arbeitskopie)
@@ -48,7 +48,7 @@
 * Introduction:         Introduction
 * @code{ABORT}:         ABORT,     Abort the program     
 * @code{ABS}:           ABS,       Absolute value     
-* @code{ACCESS}:        ACCESS,    Checks file access method
+* @code{ACCESS}:        ACCESS,    Checks file access modes
 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
 * @code{ACOS}:          ACOS,      Arccosine function
 * @code{ACOSH}:         ACOSH,     Hyperbolic arccosine function
@@ -382,26 +383,56 @@
 
 
 @node ACCESS
-@section @code{ACCESS} --- Checks file access method
+@section @code{ACCESS} --- Checks file access modes
 @findex @code{ACCESS} 
 @cindex file system functions
 
-Not yet implemented in GNU Fortran.
-
 @table @asis
 @item @emph{Description}:
+@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 
+exists, is readable, writable or executable. Except for the
+executable check, @code{ACCESS} can be replaced by
+Fortran 95's @code{INQUIRE}.
 
 @item @emph{Standard}:
 GNU extension
 
 @item @emph{Class}:
+Inquiry function
+
 @item @emph{Syntax}:
+@code{I = ACCESS(NAME, MODE)}
+
 @item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
+Tailing blank are ignored unless the character @code{achar(0)} is
+present, then all characters up to and excluding @code{achar(0)} are
+used as file name.
+@item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
+may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
+and @code{"x"} (executable), or @code{" "} to check for existance.
+@end multitable
+
 @item @emph{Return value}:
+Returns a scalar @code{INTEGER}, which is @code{0} if the file is
+accessable in the given mode; otherwise or if an invalid argument
+has been given for @code{MODE} the value @code{1} is returned.
+
 @item @emph{Example}:
-@item @emph{Specific names}:
-@item @emph{See also}:
-@uref{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=19292, g77 features lacking in gfortran}
+@smallexample
+program access_test
+  implicit none
+  character(len=*), parameter :: file  = 'test.dat'
+  character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
+  if(access(file,' ') == 0) print *, trim(file),' is exists'
+  if(access(file,'r') == 0) print *, trim(file),' is readable'
+  if(access(file,'w') == 0) print *, trim(file),' is writable'
+  if(access(file,'x') == 0) print *, trim(file),' is executable'
+  if(access(file2,'rwx') == 0) &
+    print *, trim(file2),' is readable, writable and executable'
+end program access_test
+@end smallexample
 
 @end table
 
@@ -1867,10 +1898,11 @@
 @findex @code{CHMOD} 
 @cindex file system functions
 
-Not yet implemented in GNU Fortran.
-
 @table @asis
 @item @emph{Description}:
+@code{CHMOD} changes the permissions of a file. This function invokes
+@code{/bin/chmod} and might therefore not work on all platforms.
+@code{CHMOD} as intrinsic function is not implement in GNU Fortran.
 
 @item @emph{Standard}:
 GNU extension
@@ -1879,12 +1911,32 @@
 Subroutine
 
 @item @emph{Syntax}:
+@code{CHMOD(NAME, MODE[, STATUS])}
+
 @item @emph{Arguments}:
-@item @emph{Return value}:
+@multitable @columnfractions .15 .80
+@item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
+Tailing blank are ignored unless the character @code{achar(0)} is
+present, then all characters up to and excluding @code{achar(0)} are
+used as file name.
+
+@item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
+@var{MODE} uses the same syntax as the @var{MODE} argument of
+@code{/bin/chmod}.
+
+@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
+@code{0} on success and non-zero otherwise.
+@end multitable
+
 @item @emph{Example}:
-@item @emph{Specific names}:
-@item @emph{See also}:
-@uref{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=19292, g77 features lacking in gfortran}
+@smallexample
+program chmod_test
+  implicit none
+  integer :: status
+  call chmod('test.dat','u+x',status)
+  print *, 'Status: ', status
+end program chmod_test
+@end smallexample
 
 @end table