This is the mail archive of the
fortran@gcc.gnu.org
mailing list for the GNU Fortran project.
[PATCH, Fortran] documentation for FTELL, GETLOG, HOSTNM instrinsics
- From: Brooks Moses <bmoses at stanford dot edu>
- To: fortran at gcc dot gnu dot org
- Cc: gcc-patches at gcc dot gnu dot org
- Date: Fri, 20 Oct 2006 02:24:09 -0700
- Subject: [PATCH, Fortran] documentation for FTELL, GETLOG, HOSTNM instrinsics
- Organization: Stanford University
Documentation for a few previously-undocumented intrinsics.
----------------------------------------------------------
2006-10-20 Brooks Moses <bmoses@stanford.edu>
* intrinsic.texi: Added documentation for FTELL, GETLOG, and
HOSTNM intrinsics.
----------------------------------------------------------
Tested with "make info" and "make pdf". Ok for trunk? (And for 4.2, if
this gets approved after the branch?)
In general, are example programs like the ones I included here actually
considered useful? In these cases, I'm not sure they actually add
anything to what's already covered in the Syntax section, but it was
trivial to cut-and-paste in the test programs I was using to make sure I
was documenting the actual behavior.
- Brooks
Index: intrinsic.texi
===================================================================
--- intrinsic.texi (revision 117898)
+++ intrinsic.texi (working copy)
@@ -3878,20 +3878,45 @@
@node FTELL
@section @code{FTELL} --- Current stream position
@findex @code{FTELL} intrinsic
-@cindex undocumented intrinsic
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Retrieves the current position within an open file.
+
+This intrinsic is provided in both subroutine and function forms; however,
+only one form can be used in any given program unit.
+
@item @emph{Standard}:
GNU extension
@item @emph{Class}:
+Subroutine, function
+
@item @emph{Syntax}:
+@multitable @columnfractions .80
+@item @code{CALL FTELL(UNIT, OFFSET)}
+@item @code{OFFSET = FTELL(UNIT)}
+@end multitable
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{OFFSET} @tab Shall of type @code{INTEGER}.
+@item @var{UNIT} @tab Shall of type @code{INTEGER}.
+@end multitable
+
@item @emph{Return value}:
+In either syntax, @var{OFFSET} is set to the current offset of unit
+number @var{UNIT}, or to @math{-1} if the unit is not currently open.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_ftell
+ INTEGER :: i
+ OPEN(10, FILE="temp.dat")
+ CALL ftell(10,i)
+ WRITE(*,*) i
+END PROGRAM
+@end smallexample
@item @emph{See also}:
@ref{FSEEK}
@@ -4216,7 +4241,7 @@
See @code{GETPID} for an example.
@item @emph{See also}:
-@ref{GETPID}
+@ref{GETPID}, @ref{GETUID}
@end table
@@ -4224,12 +4249,11 @@
@node GETLOG
@section @code{GETLOG} --- Get login name
@findex @code{GETLOG} intrinsic
-@cindex undocumented intrinsic
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Gets the username under which the program is running.
+
@item @emph{Standard}:
GNU extension
@@ -4237,16 +4261,33 @@
Subroutine
@item @emph{Syntax}:
+@code{CALL GETLOG(LOGIN)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
+@end multitable
+
@item @emph{Return value}:
+Stores the current user name in @var{LOGIN}. (On systems where
+the @code{getlogin(3)} function is not implemented, this will
+return a blank string.)
+
@item @emph{Example}:
-@item @emph{Specific names}:
+@smallexample
+PROGRAM TEST_GETLOG
+ CHARACTER(32) :: login
+ CALL GETLOG(login)
+ WRITE(*,*) login
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{GETUID}
@end table
-
@node GETPID
@section @code{GETPID} --- Process ID function
@findex @code{GETPID} intrinsic
@@ -4279,6 +4320,8 @@
end program info
@end smallexample
+@item @emph{See also}:
+@ref{GETGID}, @ref{GETUID}
@end table
@@ -4310,7 +4353,7 @@
See @code{GETPID} for an example.
@item @emph{See also}:
-@ref{GETPID}
+@ref{GETPID}, @ref{GETLOG}
@end table
@@ -4345,22 +4388,38 @@
@node HOSTNM
@section @code{HOSTNM} --- Get system host name
@findex @code{HOSTNM} intrinsic
-@cindex undocumented intrinsic
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Retrieves the host name of the system on which the program is running.
+
+This intrinsic is provided in both subroutine and function forms; however,
+only one form can be used in any given program unit.
+
@item @emph{Standard}:
GNU extension
@item @emph{Class}:
+Subroutine, function
+
@item @emph{Syntax}:
+@multitable @columnfractions .80
+@item @code{CALL HOSTNM(NAME, STATUS)}
+@item @code{STATUS = HOSTNM(NAME)}
+@end multitable
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
+@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
+ Returns 0 on success, or a system specific error
+ code otherwise.
+@end multitable
+
@item @emph{Return value}:
-@item @emph{Example}:
-@item @emph{Specific names}:
-@item @emph{See also}:
+In either syntax, @var{NAME} is set to the current hostname if it can
+be obtained, or to a blank string otherwise.
+
@end table