Return to f77IO.ms CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 03.f77io

Annotation of 43BSDReno/share/doc/ps1/03.f77io/f77IO.ms, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)f77IO.ms    5.4 (Berkeley) 4/28/86
        !             6: .\"
        !             7: .EH 'PS1:3-%''Introduction to the f77 I/O Library'
        !             8: .OH 'Introduction to the f77 I/O Library''PS1:3-%'
        !             9: .de Fo
        !            10: Fortran\\$1
        !            11: ..
        !            12: .de Sm
        !            13: \s-1\\$1\s0
        !            14: ..
        !            15: .\"
        !            16: .\"    Nh macro - same as NH but also saves heading for table of contents
        !            17: .\"    Nh usage: Nh level string, e.g.:  .Nh 2 "Calculator Sample"
        !            18: .de Nh
        !            19: .NH \\$1
        !            20: \\$2
        !            21: .XS
        !            22: .if '2'\\$1' .ti .25i
        !            23: .if '3'\\$1' .ti .5i
        !            24: \\*(SN \\$2
        !            25: .XE
        !            26: .PP
        !            27: ..
        !            28: .ND ""
        !            29: .\" .nr ll 7.0i
        !            30: .\" .nr LL 7.0i
        !            31: .\" .po 0.0i
        !            32: .\" .rm PT
        !            33: .\" .rm BT
        !            34: .\".RP
        !            35: .TL
        !            36: Introduction to the f77 I/O Library
        !            37: .AU
        !            38: David L. Wasley
        !            39: .AU
        !            40: J. Berkman
        !            41: .AI
        !            42: University of California, Berkeley
        !            43: Berkeley, California 94720
        !            44: .AB
        !            45: The f77 I/O library, libI77.a,
        !            46: includes routines to perform all of the standard types of
        !            47: .Fo
        !            48: input and output specified in the
        !            49: .Sm ANSI
        !            50: 1978
        !            51: .Fo
        !            52: standard.
        !            53: The I/O Library was written originally by Peter J. Weinberger at Bell Labs.
        !            54: Where the original implementation was incomplete,
        !            55: it has been rewritten to more closely implement the standard.
        !            56: Where the standard is vague,
        !            57: we have tried to provide flexibility within the constraints of the
        !            58: .UX
        !            59: operating system.
        !            60: A number of logical extensions and enhancements have been provided
        !            61: such as the use of the C stdio library routines to provide
        !            62: efficient buffering for file I/O.
        !            63: .sp 2
        !            64: .LP
        !            65: Revised September, 1985
        !            66: .AE
        !            67: .LP
        !            68: .\" page 2 is allocated to the table of contents
        !            69: .pn 3
        !            70: .bp
        !            71: .Nh 1 "Fortran I/O"
        !            72: The requirements of the
        !            73: .Sm ANSI
        !            74: standard impose significant overhead
        !            75: on programs that do large amounts of I/O. Formatted I/O can be
        !            76: very ``expensive'' while direct access binary I/O is usually very efficient.
        !            77: Because of the complexity of
        !            78: .Fo
        !            79: I/O,
        !            80: some general concepts deserve clarification.
        !            81: .Nh 2 "Types of I/O and logical records"
        !            82: There are four forms of I/O:
        !            83: .B formatted,
        !            84: .B unformatted,
        !            85: .B list\ directed,
        !            86: and
        !            87: .B namelist.
        !            88: The last two are
        !            89: related to formatted but do not obey all the rules for formatted I/O.
        !            90: There are two types of ``files'':
        !            91: .B external
        !            92: and
        !            93: .B internal
        !            94: and two modes of access to files:
        !            95: .B direct
        !            96: and
        !            97: .B sequential.
        !            98: The definition of a logical record depends upon the
        !            99: combination of I/O form, file type, and access mode specified by the
        !           100: .Fo
        !           101: I/O statement.
        !           102: .Nh 3 "Direct access external I/O"
        !           103: A logical record in a
        !           104: .B direct
        !           105: access
        !           106: .B external
        !           107: file is a string of bytes
        !           108: of a length specified when the file is opened.
        !           109: Read and write statements must not specify logical records longer than
        !           110: the original record size definition. Shorter logical records are allowed.
        !           111: .B Unformatted
        !           112: direct writes leave the unfilled part of the record undefined.
        !           113: .B Formatted
        !           114: direct writes cause the unfilled record to be padded with blanks.
        !           115: .Nh 3 "Sequential access external I/O"
        !           116: Logical records in
        !           117: .B sequentially
        !           118: accessed
        !           119: .B external
        !           120: files may be of arbitrary
        !           121: and variable length.
        !           122: Logical record length for
        !           123: .B unformatted
        !           124: sequential files is determined by
        !           125: the size of items in the iolist.
        !           126: The requirements of this form of I/O cause the external physical
        !           127: record size to be somewhat larger than the logical record size.
        !           128: For
        !           129: .B formatted
        !           130: write statements, logical record length is determined by
        !           131: the format statement interacting with the iolist at execution time.
        !           132: The ``newline'' character is the logical record delimiter.
        !           133: Formatted sequential access causes one or more logical records
        !           134: ending with ``newline'' characters to be read or written.
        !           135: .Nh 3 "List directed and namelist sequential external I/O"
        !           136: Logical record length for
        !           137: .B list\ directed
        !           138: and
        !           139: .B namelist
        !           140: I/O is relatively meaningless.
        !           141: On output, the record length is dependent on the magnitude of the
        !           142: data items.
        !           143: On input, the record length is determined by the data types and the file
        !           144: contents.
        !           145: By ANSI definition, a slash, ``/'', terminates execution of a
        !           146: list directed input operation.
        !           147: Namelist input is terminated by ``&end'' or ``$end'' (depending on whether
        !           148: the character before the namelist name was ``&'' or ``$'').
        !           149: .Nh 3 "Internal I/O"
        !           150: The logical record length for an
        !           151: .B internal
        !           152: read or write is the length of the
        !           153: character variable or array element. Thus a simple character variable
        !           154: is a single logical record. A character variable array is similar to
        !           155: a fixed length direct access file, and obeys the same rules.
        !           156: .B Unformatted
        !           157: and
        !           158: .B namelist
        !           159: I/O are not allowed on ``internal'' files.
        !           160: .Nh 2 "I/O execution"
        !           161: Note that each execution of a
        !           162: .Fo
        !           163: .B unformatted
        !           164: I/O statement causes a single
        !           165: logical record to be read or written. Each execution of a
        !           166: .Fo
        !           167: .B formatted
        !           168: I/O statement causes one or more logical records to be read or written.
        !           169: .PP
        !           170: A slash, ``/'', will terminate assignment of
        !           171: values to the input list during
        !           172: .B list\ directed
        !           173: input and the remainder of the current input line is skipped.
        !           174: The standard is rather vague on this point but seems to require that
        !           175: a new external logical record be found at the start of any formatted
        !           176: input. Therefore data following the slash is ignored and may be used
        !           177: to comment the data file.
        !           178: .PP
        !           179: .B "Direct access list directed"
        !           180: I/O is not allowed.
        !           181: .B "Unformatted internal"
        !           182: I/O is not allowed.
        !           183: .B Namelist
        !           184: I/O is allowed only with
        !           185: .B "external sequential"
        !           186: files.
        !           187: All other flavors of I/O are allowed, although some are not part of the
        !           188: .Sm ANSI
        !           189: standard.
        !           190: .PP
        !           191: Any I/O statement may include an
        !           192: .B err=
        !           193: clause to specify an alternative branch to be taken on errors
        !           194: and/or an
        !           195: .B iostat=
        !           196: clause to return the specific error code.
        !           197: Any error detected during I/O processing will cause the program to abort
        !           198: unless either
        !           199: .B err=
        !           200: or
        !           201: .B iostat=
        !           202: has been specificed in the program.
        !           203: Read statements may include
        !           204: .B end=
        !           205: to branch on end-of-file.
        !           206: The end-of-file indication for that logical unit may be reset with
        !           207: a \fBbackspace\fP statement.
        !           208: File position and the value of I/O list items is undefined following an error.
        !           209: .sp 1
        !           210: .Nh 1 "Implementation details"
        !           211: Some details of the current implementation may be useful in understanding
        !           212: constraints on
        !           213: .Fo
        !           214: I/O.
        !           215: .Nh 2 "Number of logical units"
        !           216: Unit numbers must be in the range 0 \- 99.
        !           217: The maximum number of logical units that a program may have open at one
        !           218: time is the same as the
        !           219: .UX
        !           220: system limit, currently 48.
        !           221: .Nh 2 "Standard logical units"
        !           222: By default, logical units 0, 5, and 6
        !           223: are opened to ``stderr'', ``stdin'', and ``stdout'' respectively.
        !           224: However they can be re-defined with an 
        !           225: .B open
        !           226: statement.
        !           227: To preserve error reporting, it is an error to close logical unit 0
        !           228: although it may be reopened to another file.
        !           229: .PP
        !           230: If you want to open the default file name for any preconnected logical unit,
        !           231: remember to 
        !           232: .B close
        !           233: the unit first.
        !           234: Redefining the standard units may impair normal console I/O.
        !           235: An alternative is to
        !           236: use shell re-direction to externally re-define the above units.
        !           237: To re-define default blank control or format of the standard input or output
        !           238: files, use the 
        !           239: .B open
        !           240: statement specifying the unit number and no
        !           241: file name (see \(sc\|2.4).
        !           242: .PP
        !           243: The standard units, 0, 5, and 6, are named internally ``stderr'', ``stdin'',
        !           244: and ``stdout'' respectively.
        !           245: These are not actual file names and can not be used for opening these units.
        !           246: .B Inquire
        !           247: will not return these names and will indicate
        !           248: that the above units are not named unless they have been opened to real files.
        !           249: The names are meant to make error reporting more meaningful.
        !           250: .Nh 2 "Vertical format control"
        !           251: Simple vertical format control is implemented. The logical unit must be opened
        !           252: for sequential access with
        !           253: .B "form = \(fmprint\(fm"
        !           254: (see \(sc\|3.2).
        !           255: Control codes ``0'' and ``1'' are replaced in the output file
        !           256: with ``\\n'' and ``\\f'' respectively.
        !           257: The control character ``+'' is not implemented and, like
        !           258: any other character in the first position of a record
        !           259: written to a ``print'' file, is dropped.
        !           260: The
        !           261: .B "form = \(fmprint\(fm"
        !           262: mode does not recognize vertical format control for
        !           263: .B "direct formatted, list directed,"
        !           264: or
        !           265: .B "namelist"
        !           266: output.
        !           267: .PP
        !           268: An alternative is to use
        !           269: the filter \fIfpr\fP(1) for vertical format control.
        !           270: It replaces ``0'' and ``1'' by
        !           271: ``\\n'' and ``\\f'' respectively, and implements the ``+'' control code.
        !           272: Unlike
        !           273: .B "form = \(fmprint\(fm"
        !           274: which drops unrecognized form control characters, \fIfpr\fP copies those
        !           275: characters to the output file.
        !           276: .Nh 2 "File names and the open statement"
        !           277: A file name may be specified in an \fBopen\fP statement for the
        !           278: logical unit.
        !           279: If a logical unit is opened by an \fBopen\fP statement which does
        !           280: not specify a file name, or it is opened implicitly by the execution
        !           281: of a \fBread\fP, \fBwrite\fP, or \fBendfile\fP
        !           282: statement, then the default file name is
        !           283: .I fort.N
        !           284: where
        !           285: .I N
        !           286: is the logical unit number.
        !           287: Before opening the file, the library checks for an environment
        !           288: variable with a name identical to the tail of the
        !           289: file name with periods removed.\(dg
        !           290: .FS
        !           291: \(dgPeriods are deleted because they can not be part of environment variable names in the Bourne shell.
        !           292: .FE
        !           293: If it finds such an environment variable, it uses its value
        !           294: as the actual name of the file.
        !           295: For example, a program containing:
        !           296: .DS
        !           297: open(32,file=\(fm/usr/guest/census/data.d\(fm)
        !           298: read(32,100) vec
        !           299: write(44) vec
        !           300: .DE
        !           301: normally will read from \fI/usr/guest/census/data.d\fP and write to
        !           302: \fIfort.44\fP in the current directory.
        !           303: If the environment variables \fIdatad\fP and \fIfort44\fP are set,
        !           304: e.g.:
        !           305: .DS
        !           306: % setenv datad mydata
        !           307: % setenv fort44 myout
        !           308: .DE
        !           309: in the C shell or:
        !           310: .DS
        !           311: $ datad=mydata
        !           312: $ fort44=myout
        !           313: $ export datad fort44
        !           314: .DE
        !           315: in the Bourne shell, then the program will read from \fImydata\fP and
        !           316: write to \fImyout\fP.
        !           317: .PP
        !           318: An
        !           319: .B open
        !           320: statement need not specify a file name. If it refers to a logical
        !           321: unit that is already open, the 
        !           322: .B blank=
        !           323: and 
        !           324: .B form=
        !           325: specifiers may be
        !           326: redefined without affecting the current file position.
        !           327: Otherwise, if
        !           328: .B "status = \(fmscratch\(fm"
        !           329: is specified, a temporary file with a
        !           330: name of the form
        !           331: .I tmp.FXXXXXX
        !           332: will be opened,
        !           333: and, by default, will be deleted when closed or during
        !           334: termination of program execution.
        !           335: .PP
        !           336: It is an error to try to open an existing file with
        !           337: .B "status = \(fmnew\(fm"
        !           338: \&.
        !           339: It is an error to try to open a nonexistent file with
        !           340: .B "status = \(fmold\(fm"
        !           341: \&.
        !           342: By default,
        !           343: .B "status = \(fmunknown\(fm"
        !           344: will be assumed, and a file will be created if necessary.
        !           345: .PP
        !           346: By default, files are positioned
        !           347: at their beginning upon opening, but see \fIfseek\fP(3f)
        !           348: and \fIioinit\fP(3f) for alternatives.
        !           349: Existing files are never truncated on opening.
        !           350: Sequentially accessed external files are truncated to the current file
        !           351: position on \fBclose\fP, \fBbackspace\fP, or \fBrewind\fP only if the last
        !           352: access to the file was a write.
        !           353: An
        !           354: .B endfile
        !           355: always causes such files to be truncated to the current
        !           356: file position.
        !           357: .Nh 2 "Format interpretation"
        !           358: Formats which are in format statements are parsed by the compiler;
        !           359: formats in \fBread\fP, \fBwrite\fP, and \fBprint\fP statements
        !           360: are parsed during execution by the
        !           361: .Sm I/O
        !           362: library.
        !           363: Upper as well as lower case characters are recognized in format statements
        !           364: and all the alphabetic arguments to the I/O library routines.
        !           365: .PP
        !           366: If the external representation of a datum
        !           367: is too large for the field width specified, the specified
        !           368: field is filled with asterisks (\(**).
        !           369: On \fBE\fPw.d\fBE\fPe output,
        !           370: the exponent field will be filled with asterisks if the
        !           371: exponent representation is too large.
        !           372: This will only happen if ``e'' is zero (see appendix B).
        !           373: .PP
        !           374: On output, a real value that is truly zero will display as ``0.'' to
        !           375: distinguish it from a very small non-zero value.
        !           376: If this causes problems for other input systems, the
        !           377: \fBBZ\fP edit descriptor may be used to cause the field
        !           378: following the decimal point to be filled with zero's.
        !           379: .PP
        !           380: Non-destructive tabbing is implemented for both internal and external
        !           381: formatted I/O.
        !           382: Tabbing left or right on output
        !           383: does not affect previously written portions of a record.
        !           384: Tabbing right on output
        !           385: causes unwritten portions of a record to be filled with blanks.
        !           386: Tabbing right off the end of an input logical record is an error.
        !           387: Tabbing left beyond the beginning of an input logical record leaves
        !           388: the input pointer at the beginning of the record.
        !           389: The format specifier
        !           390: .B T
        !           391: must be followed by a positive non-zero number.
        !           392: If it is not, it will have a different meaning (see \(sc\|3.1).
        !           393: .PP
        !           394: Tabbing left requires seek ability on the logical unit.
        !           395: Therefore it is not allowed in I/O to a terminal or pipe.
        !           396: Likewise, nondestructive tabbing in either direction is possible
        !           397: only on a unit that can seek. Otherwise tabbing right or spacing with
        !           398: .B X
        !           399: will write blanks on the output.
        !           400: .Nh 2 "List directed output"
        !           401: In formatting list directed output, the I/O system tries to prevent
        !           402: output lines longer than 80 characters.
        !           403: Each external datum will be separated by two spaces.
        !           404: List directed output of
        !           405: .B complex
        !           406: values includes an appropriate comma.
        !           407: List directed output distinguishes between
        !           408: .B real
        !           409: and
        !           410: .B "double precision"
        !           411: values and formats them differently.
        !           412: Output of a character string that includes ``\\n''
        !           413: is interpreted reasonably by the output system.
        !           414: .Nh 2 "I/O errors"
        !           415: If I/O errors are not trapped by the user's program an appropriate
        !           416: error message will be written to ``stderr'' before aborting.
        !           417: An error number will be printed in ``[ ]'' along with a brief error message
        !           418: showing the logical unit and I/O state.
        !           419: Error numbers < 100 refer to
        !           420: .UX
        !           421: errors, and are described in the
        !           422: introduction to chapter 2 of the
        !           423: .UX
        !           424: Programmer's Manual.
        !           425: Error numbers \(>= 100 come from the I/O library, and are described
        !           426: further in the appendix to this writeup\(dd.
        !           427: .FS
        !           428: \(dd On many systems, these are also available in \fIhelp f77 io_err_msgs\fP.
        !           429: .FE
        !           430: For internal I/O, part of the string will be printed with ``|'' at the
        !           431: current position in the string.
        !           432: For external I/O, part of the current record will be displayed if
        !           433: the error was caused during reading from a file that can backspace.
        !           434: .sp 1
        !           435: .Nh 1 "Non-``ANSI Standard'' extensions"
        !           436: Several extensions have been added to the I/O system to provide
        !           437: for functions omitted or poorly defined in the standard.
        !           438: Programmers should be aware that these are non-portable.
        !           439: .Nh 2 "Format specifiers"
        !           440: .B B
        !           441: is an acceptable edit control specifier. It causes return to the logical unit's
        !           442: default mode of blank interpretation.
        !           443: This is consistent with
        !           444: .B S
        !           445: which returns to default sign control.
        !           446: .PP
        !           447: .B P
        !           448: by itself is equivalent to
        !           449: .B 0P
        !           450: \&. It resets the scale factor to the
        !           451: default value, 0.
        !           452: .PP
        !           453: The form of the \fBE\fPw.d\fBE\fPe format specifier has been extended to
        !           454: .B D
        !           455: also.
        !           456: The form \fBE\fPw.d.e is allowed but is not standard.
        !           457: The ``e'' field specifies the minimum number of digits or spaces in the
        !           458: exponent field on output.
        !           459: If the value of the exponent is too large, the exponent notation
        !           460: .B e
        !           461: or
        !           462: .B d
        !           463: will be dropped from the output to allow one
        !           464: more character position.
        !           465: If this is still not adequate, the ``e'' field will be filled with
        !           466: asterisks (\(**).
        !           467: The default value for ``e'' is 2.
        !           468: .PP
        !           469: An additional form of tab control specification has been added.
        !           470: The
        !           471: .Sm ANSI
        !           472: standard forms \fBTR\fPn, \fBTL\fPn, and \fBT\fPn are supported
        !           473: where
        !           474: .I n
        !           475: is a positive non-zero number.
        !           476: If
        !           477: .B T
        !           478: or n\fBT\fP is specified, tabbing will
        !           479: be to the next (or n-th) 8-column tab stop.
        !           480: Thus columns of alphanumerics can be lined up without counting.
        !           481: .PP
        !           482: A format control specifier has been added to suppress the newline
        !           483: at the end of the last record of a formatted sequential write. The
        !           484: specifier is a dollar sign ($). It is constrained by the same rules
        !           485: as the colon (:). It is used typically for console prompts.
        !           486: For example:
        !           487: 
        !           488: .DS
        !           489: write (\(**, "(\(fmenter value for x: \(fm,$)")
        !           490: read (\(**,\(**) x
        !           491: .DE
        !           492: .PP
        !           493: Radices other than 10 can be specified for formatted integer I/O
        !           494: conversion. The specifier is patterned after
        !           495: .B P,
        !           496: the scale factor for
        !           497: floating point conversion. It remains in effect until another radix is
        !           498: specified or format interpretation is complete. The specifier is defined
        !           499: as [n]\fBR\fP where 2 \(<= \fIn\fP \(<= 36. If
        !           500: .I n
        !           501: is omitted,
        !           502: the default decimal radix is restored.
        !           503: .PP
        !           504: The format specifier \fBO\fPm.n may be used for an octal conversion;
        !           505: it is equivalent to 8\fBR,I\fPm.n,10\fBR\fP.
        !           506: Similarly, \fBZ\fPm.n is equivalent to 16\fBR,I\fPm.n,10\fBR\fP and
        !           507: may be used for an hexadecimal conversion;
        !           508: .PP
        !           509: In conjunction with the above, a sign control specifier has been added
        !           510: to cause integer values to be interpreted as unsigned during output
        !           511: conversion. The specifier is
        !           512: .B SU
        !           513: and remains in effect until another
        !           514: sign control specifier is encountered, or format interpretation is
        !           515: complete.\(dg
        !           516: .FS
        !           517: \(dgNote: Unsigned integer values greater than (2\(**\(**31 - 1),
        !           518: can be read and written using \fBSU\fP.
        !           519: However they can not be used in
        !           520: computations because
        !           521: .Fo
        !           522: uses signed arithmetic and such values appear to the arithmetic unit
        !           523: as negative numbers.
        !           524: .FE
        !           525: Radix and ``unsigned'' specifiers could be used to format
        !           526: a hexadecimal dump, as follows:
        !           527: 
        !           528: .DS
        !           529: 2000  format ( SU, 8Z10.8 )
        !           530: .DE
        !           531: 
        !           532: .Nh 2 "Print files"
        !           533: The
        !           534: .Sm ANSI
        !           535: standard is ambiguous regarding the definition of a ``print'' file.
        !           536: Since
        !           537: .UX
        !           538: has no default ``print'' file, an additional
        !           539: .B form=
        !           540: specifier
        !           541: is now recognized in the
        !           542: .B open
        !           543: statement.
        !           544: Specifying
        !           545: .B "form = \(fmprint\(fm"
        !           546: implies
        !           547: .B formatted
        !           548: and enables vertical format
        !           549: control for that logical unit (see \(sc\|2.3).
        !           550: Vertical format control is interpreted only on sequential formatted writes
        !           551: to a ``print'' file.
        !           552: .PP
        !           553: The
        !           554: .B inquire
        !           555: statement will return
        !           556: .B print
        !           557: in the
        !           558: .B form=
        !           559: string variable
        !           560: for logical units opened as ``print'' files.
        !           561: It will return -1 for the unit number of an unconnected file.
        !           562: .PP
        !           563: If a logical unit is already open, an
        !           564: .B open
        !           565: statement including the
        !           566: .B form=
        !           567: option or the
        !           568: .B blank=
        !           569: option will do nothing but re-define those options.
        !           570: This instance of the
        !           571: .B open
        !           572: statement need not include the file name, and
        !           573: must not include a file name if
        !           574: .B unit=
        !           575: refers to a standard input or output.
        !           576: Therefore, to re-define the standard output as a ``print'' file, use:
        !           577: 
        !           578: .DS
        !           579: open (unit=6, form=\(fmprint\(fm)
        !           580: .DE
        !           581: .Nh 2 "Scratch files"
        !           582: A
        !           583: .B close
        !           584: statement with
        !           585: .B "status = \(fmkeep\(fm"
        !           586: may be specified for temporary files.
        !           587: This is the default for all other files.
        !           588: Remember to get the scratch file's real name,
        !           589: using
        !           590: .B inquire
        !           591: \&, if you want to re-open it later.
        !           592: .Nh 2 "List directed I/O"
        !           593: List directed read has been modified to allow
        !           594: tab characters wherever blanks are allowed.
        !           595: It also allows input of a string not enclosed in quotes.
        !           596: The string must not start with a digit or quote,
        !           597: and can not contain any separators ( ``,'', ``/'', blank or tab ).
        !           598: A newline will terminate the string unless escaped with \\.
        !           599: Any string not meeting the above restrictions
        !           600: must be enclosed in quotes (`` " '' or `` \(fm '').
        !           601: .PP
        !           602: Internal list directed I/O has been implemented. During internal list reads,
        !           603: bytes are consumed until the iolist is satisfied, or the ``end-of-file''
        !           604: is reached.
        !           605: During internal list writes, records are filled until the iolist is satisfied.
        !           606: The length of an internal array element should be at least 20 bytes to
        !           607: avoid logical record overflow when writing double precision values.
        !           608: Internal list read was implemented to make command line decoding easier.
        !           609: Internal list write should be avoided.
        !           610: .Nh 2 "Namelist I/O"
        !           611: Namelist I/O is a common extension in Fortran systems.
        !           612: The \fBf77\fP version was designed to be compatible with other
        !           613: vendors versions;
        !           614: it is described in ``A Portable Fortran 77 Compiler'',
        !           615: by Feldman and Weinberger, August, 1985.
        !           616: .sp 1
        !           617: .Nh 1 "Running older programs"
        !           618: Traditional
        !           619: .Fo
        !           620: environments usually assume carriage control on all logical units,
        !           621: usually interpret blank spaces on input as ``0''s, and often provide
        !           622: attachment of global file names to logical units at run time.
        !           623: There are several routines in the I/O library to provide these functions.
        !           624: .Nh 2 "Traditional unit control parameters"
        !           625: If a program reads and writes only units 5 and 6, then including
        !           626: .B \-lI66
        !           627: in the f77 command will cause carriage control to be interpreted on
        !           628: output and cause blanks to be zeros on input without further
        !           629: modification of the program.
        !           630: If this is not adequate,
        !           631: the routine \fIioinit\fP(3f) can be called to specify control parameters
        !           632: separately, including whether files should be positioned at their
        !           633: beginning or end upon opening.
        !           634: .Nh 2 "Ioinit()"
        !           635: \fIIoinit\fP(3f) can be used to attach logical units
        !           636: to specific files at run time, and to set global parameters for the
        !           637: .Sm I/O
        !           638: system.
        !           639: It will look for names of a user specified form in the environment
        !           640: and open the corresponding logical unit for
        !           641: .B "sequential formatted"
        !           642: I/O. Names must be of the form \fB\s-1PREFIX\s0\fP\fInn\fP where
        !           643: .B \\s-1PREFIX\\s0
        !           644: is specified in the call to
        !           645: .I ioinit
        !           646: and
        !           647: .I nn
        !           648: is the logical unit to be opened. Unit numbers < 10 must include
        !           649: the leading ``0''.
        !           650: .PP
        !           651: .I Ioinit
        !           652: should prove adequate for most programs as written.
        !           653: However, it
        !           654: is written in
        !           655: .Fo \-77
        !           656: specifically so that it may serve as an example for similar
        !           657: user-supplied routines.
        !           658: A copy may be retrieved by ``ar x /usr/lib/libU77.a ioinit.f''.
        !           659: See \(sc\|2.4 for another way to override program file names
        !           660: through environment variables.
        !           661: .sp 1
        !           662: .Nh 1 "Magnetic tape I/O"
        !           663: Because the I/O library uses stdio buffering, reading or writing
        !           664: magnetic tapes should be done with great caution, or avoided if possible.
        !           665: A set of routines has been provided to read and write arbitrary sized buffers
        !           666: to or from tape directly. The buffer must be a
        !           667: .B character
        !           668: object.
        !           669: .B Internal
        !           670: I/O can be used to fill or interpret the buffer.
        !           671: These routines do not use normal
        !           672: .Fo
        !           673: I/O processing and do not obey
        !           674: .Fo
        !           675: I/O rules.
        !           676: See \fItopen\fP(3f).
        !           677: .sp 1
        !           678: .Nh 1 "Caveat Programmer"
        !           679: The I/O library is extremely complex yet we believe there are few bugs left.
        !           680: We've tried to make the system as correct as possible according to
        !           681: the
        !           682: .Sm ANSI
        !           683: X3.9\-1978 document and keep it compatible with the
        !           684: .UX
        !           685: file system.
        !           686: Exceptions to the standard are noted in appendix B.
        !           687: .bp
        !           688: .DS C
        !           689: .B "Appendix A"
        !           690: 
        !           691: .B "I/O Library Error Messages"
        !           692: .DE
        !           693: .XS
        !           694: Appendix A: I/O Library Error Messages
        !           695: .XE
        !           696: .sp 1
        !           697: .PP
        !           698: The following error messages are generated by the I/O library.
        !           699: The error numbers are returned in the \fBiostat=\fP variable.
        !           700: Error numbers < 100 are generated by the
        !           701: .UX
        !           702: kernel.
        !           703: See the introduction to chapter 2 of the
        !           704: .UX
        !           705: Programmers Manual for their description.
        !           706: .nr PD 0
        !           707: .de Er
        !           708: .ne 4v
        !           709: .IP \\$1
        !           710: \fI\\$2\fP
        !           711: .br
        !           712: ..
        !           713: .RS
        !           714: 
        !           715: .Er 100 "error in format"
        !           716: See error message output for the location
        !           717: of the error in the format. Can be caused
        !           718: by more than 10 levels of nested parentheses, or
        !           719: an extremely long format statement.
        !           720: 
        !           721: .Er 101 "illegal unit number"
        !           722: It is illegal to close logical unit 0.
        !           723: Unit numbers must be between 0 and 99 inclusive.
        !           724: 
        !           725: .Er 102 "formatted i/o not allowed"
        !           726: The logical unit was opened for
        !           727: unformatted I/O.
        !           728: 
        !           729: .Er 103 "unformatted i/o not allowed"
        !           730: The logical unit was opened for
        !           731: formatted I/O.
        !           732: 
        !           733: .Er 104 "direct i/o not allowed"
        !           734: The logical unit was opened for sequential
        !           735: access, or the logical record length was
        !           736: specified as 0.
        !           737: 
        !           738: .Er 105 "sequential i/o not allowed"
        !           739: The logical unit was opened for direct
        !           740: access I/O.
        !           741: 
        !           742: .Er 106 "can't backspace file"
        !           743: The file associated with the logical unit
        !           744: can't seek. May be a device or a pipe.
        !           745: 
        !           746: .Er 107 "off beginning of record"
        !           747: The format specified a left tab beyond the
        !           748: beginning of an internal input record.
        !           749: 
        !           750: .Er 108 "can't stat file"
        !           751: The system can't return status information
        !           752: about the file. Perhaps the directory is
        !           753: unreadable.
        !           754: 
        !           755: .Er 109 "no \(** after repeat count"
        !           756: Repeat counts in list directed I/O must be
        !           757: followed by an \(** with no blank spaces.
        !           758: 
        !           759: .Er 110 "off end of record"
        !           760: A formatted write tried to go beyond the
        !           761: logical end-of-record. An unformatted read
        !           762: or write will also cause this.
        !           763: 
        !           764: .Er 111 "truncation failed"
        !           765: The truncation of an external sequential file on
        !           766: .B close ,
        !           767: .B backspace ,
        !           768: .B rewind ,
        !           769: or
        !           770: .B endfile
        !           771: failed.
        !           772: 
        !           773: .Er 112 "incomprehensible list input"
        !           774: List input has to be just right.
        !           775: 
        !           776: .Er 113 "out of free space"
        !           777: The library dynamically creates buffers for
        !           778: internal use. You ran out of memory for this.
        !           779: Your program is too big!
        !           780: 
        !           781: .Er 114 "unit not connected"
        !           782: The logical unit was not open.
        !           783: 
        !           784: .Er 115 "invalid data for integer format term"
        !           785: Only spaces, a leading sign and digits are allowed.
        !           786: 
        !           787: .Er 116 "invalid data for logical format term"
        !           788: Legal input consists of spaces (optional), a period (optional), and then
        !           789: a ``t'', ``T'', ``f'', or ``F''.
        !           790: 
        !           791: .Er 117 "\|\(fmnew\|\(fm file exists"
        !           792: You tried to open an existing file with
        !           793: ``status=\|\(fmnew\|\(fm''.
        !           794: 
        !           795: .Er 118 "can't find \|\(fmold\|\(fm file"
        !           796: You tried to open a non-existent file
        !           797: with ``status=\|\(fmold\|\(fm''.
        !           798: 
        !           799: .Er 119 "opening too many files or unknown system error"
        !           800: Either you are trying to open too many files
        !           801: simultaneously or there has been an undetected system error.
        !           802: 
        !           803: .Er 120 "requires seek ability"
        !           804: Direct access requires seek ability.
        !           805: Sequential unformatted I/O requires seek
        !           806: ability on the file due to the special
        !           807: data structure required. Tabbing left
        !           808: also requires seek ability.
        !           809: 
        !           810: .Er 121 "illegal argument"
        !           811: Certain arguments to
        !           812: .B open ,
        !           813: etc. will be
        !           814: checked for legitimacy. Often only non-default
        !           815: forms are looked for.
        !           816: 
        !           817: .Er 122 "negative repeat count"
        !           818: The repeat count for list directed input
        !           819: must be a positive integer.
        !           820: 
        !           821: .Er 123 "illegal operation for unit"
        !           822: An operation was requested for a device
        !           823: associated with the logical unit which
        !           824: was not possible. This error is returned
        !           825: by the tape I/O routines if attempting to
        !           826: read past end-of-tape, etc.
        !           827: 
        !           828: .Er 124 "invalid data for d, e, f or g format term"
        !           829: Input data must be legal.
        !           830: 
        !           831: .Er 125 "illegal input for namelist"
        !           832: Column one of input is ignored, the namelist name
        !           833: must match, the variables must be in the namelist,
        !           834: and the data must be of the right type.
        !           835: .if n .nr PD 1v
        !           836: .if t .nr PD 0.3v
        !           837: .RE
        !           838: .bp
        !           839: .LP
        !           840: .DS C
        !           841: .B "Appendix B"
        !           842: 
        !           843: .B "Exceptions to the ANSI Standard"
        !           844: .DE
        !           845: .XS
        !           846: Appendix B: Exceptions to the ANSI Standard
        !           847: .XE
        !           848: .sp 1
        !           849: .PP
        !           850: A few exceptions to the
        !           851: .Sm ANSI
        !           852: standard remain.
        !           853: .sp 1
        !           854: .LP
        !           855: .B "Vertical format control"
        !           856: .PP
        !           857: The ``+'' carriage control specifier is not fully implemented
        !           858: (see \(sc\|2.3).
        !           859: It would be difficult to implement it correctly and still
        !           860: provide
        !           861: .UX -like
        !           862: file I/O.
        !           863: .PP
        !           864: Furthermore, the carriage control implementation is asymmetrical.
        !           865: A file written with carriage control interpretation can not be
        !           866: read again with the same characters in column 1.
        !           867: .PP
        !           868: An alternative to interpreting carriage control internally is to
        !           869: run the output file through a ``Fortran output filter''
        !           870: before printing. This filter could recognize a much broader range
        !           871: of carriage control and include terminal dependent processing.
        !           872: One such filter is \fIfpr\fP(1).
        !           873: .sp 1
        !           874: .LP
        !           875: .B "Default files"
        !           876: .PP
        !           877: Files created by default use of
        !           878: .B endfile
        !           879: statements are opened for
        !           880: .B "sequential formatted"
        !           881: access. There is no way to redefine such a file to allow
        !           882: .B direct
        !           883: or
        !           884: .B unformatted
        !           885: access.
        !           886: .sp 1
        !           887: .LP
        !           888: .B "Lower case strings"
        !           889: .PP
        !           890: It is not clear if the
        !           891: .Sm ANSI
        !           892: standard requires internally generated strings to be upper case or not.
        !           893: As currently written, the
        !           894: .B inquire
        !           895: statement will return lower case strings for any alphanumeric data.
        !           896: .sp 1
        !           897: .LP
        !           898: .B "Exponent representation on Ew.dEe output"
        !           899: .PP
        !           900: If the field width for the exponent is too small, the standard
        !           901: allows dropping the exponent character but only if the exponent
        !           902: is > 99. This system does not enforce that restriction.
        !           903: Further, the standard implies that the entire field, ``w'', should be
        !           904: filled with asterisks if the exponent can not be displayed.
        !           905: This system fills only the exponent field in the above case since
        !           906: that is more diagnostic.
        !           907: .sp 1
        !           908: .LP
        !           909: .B "Pre-connection of files"
        !           910: .PP
        !           911: The standard says units must be pre-connected to files before the program
        !           912: starts or must be explicitly opened.
        !           913: Instead, the I/O library
        !           914: connects the unit to a file on its first use in a
        !           915: \fBread\fP, \fBwrite\fP, \fBprint\fP, or \fBendfile\fP statement.
        !           916: Thus \fBinquire\fP by unit can not tell prior to a unit number use the
        !           917: characteristics or name of the file corresponding to a unit.
        !           918: .\" want Table of Contents to begin on page 2 hence must expand body
        !           919: .\" of .TC macro to enable us to get handle on page number.
        !           920: .pn 2
        !           921: .bp
        !           922: .PX

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.