![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to io_details CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / new / help / src / f77|
Return to io_details CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / new / help / src / f77 |
1.1 root 1: . \" this is the same as /usr/doc/f77/f77IO.ms, 4.3 version
2: . \" I/O errors split into "help f77 io_err_msgs"
3: . \" LOTS of other formatting changes to get this to work.
4: .de UX
5: UNIX
6: ..
7: . \" .I and .B - put in quotes instead of bold and italic
8: .de B
9: \&\'\\$1\'\\$2
10: ..
11: .de I
12: \&\'\\$1\'
13: ..
14: . \" Sm - in original, made it smaller
15: .de Sm
16: \\$1
17: ..
18: .de Nh
19: .NH \\$1
20: \\$2
21: .PP
22: ..
23: . \" NH - numbered header - borrowed from -ms
24: .de NH
25: .SH
26: .nr NS \\$1
27: .if !\\n(.$ .nr NS 1
28: .if !\\n(NS .nr NS 1
29: .nr H\\n(NS +1
30: .if !\\n(NS-4 .nr H5 0
31: .if !\\n(NS-3 .nr H4 0
32: .if !\\n(NS-2 .nr H3 0
33: .if !\\n(NS-1 .nr H2 0
34: .if !\\$1 .if \\n(.$ .nr H1 1
35: .ds SN \\n(H1.
36: .if \\n(NS-1 .as SN \\n(H2.
37: .if \\n(NS-2 .as SN \\n(H3.
38: .if \\n(NS-3 .as SN \\n(H4.
39: .if \\n(NS-4 .as SN \\n(H5.
40: \\*(SN
41: ..
42: .de Fo
43: Fortran\\$1
44: ..
45: .TI F77/IO_DETAILS "June 15, 1985"
46: Introduction to the f77 I/O Library
47: .na
48: .ce
49: David L. Wasley
50: .PP
51: The f77 I/O library, libI77.a,
52: includes routines to perform all of the standard types of
53: .Fo
54: input and output.
55: Several enhancements and extensions to
56: .Fo
57: I/O have been added.
58: The f77 library routines use the C stdio library routines to provide
59: efficient buffering for file I/O.
60: .sp 1
61: .Nh 1 "Fortran I/O"
62: The requirements of the
63: .Sm ANSI
64: standard impose significant overhead
65: on programs that do large amounts of I/O. Formatted I/O can be
66: very ``expensive'' while direct access binary I/O is usually very efficient.
67: Because of the complexity of
68: .Fo
69: I/O,
70: some general concepts deserve clarification.
71: .Nh 2 "Types of I/O"
72: There are three forms of I/O:
73: .B formatted ,
74: .B unformatted ,
75: and
76: .B list-directed .
77: The last is
78: related to formatted but does not obey all the rules for formatted I/O.
79: There are two modes of access to
80: .B external
81: and
82: .B internal
83: files:
84: .B direct
85: and
86: .B sequential .
87: The definition of a logical record depends upon the
88: combination of I/O form and mode specified by the
89: .Fo
90: I/O statement.
91: .Nh 3 "Direct access"
92: A logical record in a
93: .B direct
94: access
95: .B external
96: file is a string of bytes
97: of a length specified when the file is opened.
98: Read and write statements must not specify logical records longer than
99: the original record size definition. Shorter logical records are allowed.
100: .B Unformatted
101: direct writes leave the unfilled part of the record undefined.
102: .B Formatted
103: direct writes cause the unfilled record to be padded with blanks.
104: .Nh 3 "Sequential access"
105: Logical records in
106: .B sequentially
107: accessed
108: .B external
109: files may be of arbitrary
110: and variable length.
111: Logical record length for
112: .B unformatted
113: sequential files is determined by
114: the size of items in the iolist.
115: The requirements of this form of I/O cause the external physical
116: record size to be somewhat larger than the logical record size.
117: For
118: .B formatted
119: write statements, logical record length is determined by
120: the format statement interacting with the iolist at execution time.
121: The ``newline'' character is the logical record delimiter.
122: Formatted sequential access causes one or more logical records
123: ending with ``newline'' characters to be read or written.
124: .Nh 3 "List directed I/O"
125: Logical record length for
126: .B list-directed
127: I/O is relatively meaningless.
128: On output, the record length is dependent on the magnitude of the
129: data items.
130: On input, the record length is determined by the data types and the file
131: contents.
132: By ANSI definition, a slash, ``/'', terminates execution of a
133: list-directed input operation.
134: .Nh 3 "Internal I/O"
135: The logical record length for an
136: .B internal
137: read or write is the length of the
138: character variable or array element. Thus a simple character variable
139: is a single logical record. A character variable array is similar to
140: a fixed length direct access file, and obeys the same rules.
141: .B Unformatted
142: I/O is not allowed on "internal" files.
143: .Nh 2 "I/O execution"
144: Note that each execution of a
145: .Fo
146: .B unformatted
147: I/O statement causes a single
148: logical record to be read or written. Each execution of a
149: .Fo
150: .B formatted
151: I/O statement causes one or more logical records to be read or written.
152: .PP
153: A slash, ``/'', will terminate assignment of
154: values to the input list during
155: .B list-directed
156: input and the remainder of the current input line is skipped.
157: The standard is rather vague on this point but seems to require that
158: a new external logical record be found at the start of any formatted
159: input. Therefore data following the slash is ignored and may be used
160: to comment the data file.
161: .PP
162: .B "Direct access list-directed"
163: I/O is not allowed.
164: .B "Unformatted internal"
165: I/O is not allowed.
166: Both the above will be caught by the compiler.
167: All other flavors of I/O are allowed, although some are not part of the
168: .Sm ANSI
169: standard.
170: .PP
171: Any I/O statement may include an
172: .B err=
173: clause to specify an alternative branch to be taken on errors
174: and/or an
175: .B iostat=
176: clause to return the specific error code.
177: Any error detected during I/O processing will cause the program to abort
178: unless either
179: .B err=
180: or
181: .B iostat=
182: has been specificed in the program.
183: Read statements may include
184: .B end=
185: to branch on end-of-file.
186: The end-of-file indication for that logical unit may be reset with a
187: .B backspace
188: statement.
189: File position and the value of I/O list items is undefined following an error.
190: .sp 1
191: .Nh 1 "Implementation details"
192: Some details of the current implementation may be useful in understanding
193: constraints on
194: .Fo
195: I/O.
196: .Nh 2 "Number of logical units"
197: Unit numbers must be in the range 0 \- 99.
198: The maximum number of logical units that a program may have open at one
199: time is the same as the
200: .UX
201: system limit, currently 48.
202: .Nh 2 "Standard logical units"
203: By default, logical units 0, 5, and 6
204: are opened to ``stderr'', ``stdin'', and ``stdout'' respectively.
205: However they can be re-defined with an
206: .B open
207: statement.
208: To preserve error reporting, it is an error to close logical unit 0
209: although it may be reopened to another file.
210: .PP
211: If you want to open the default file name for any preconnected logical unit,
212: remember to
213: .B close
214: the unit first.
215: Redefining the standard units may impair normal console I/O.
216: An alternative is to
217: use shell re-direction to externally re-define the above units.
218: To re-define default blank control or format of the standard input or output
219: files, use the
220: .B open
221: statement specifying the unit number and no
222: file name (see section 2.4).
223: .PP
224: The standard units, 0, 5, and 6, are named internally ``stderr'', ``stdin'',
225: and ``stdout'' respectively.
226: These are not actual file names and can not be used for opening these units.
227: .B Inquire
228: will not return these names and will indicate
229: that the above units are not named unless they have been opened to real files.
230: The names are meant to make error reporting more meaningful.
231: .Nh 2 "Vertical format control"
232: Simple vertical format control is implemented. The logical unit must be opened
233: for sequential access with "form = 'print'"
234: (see section 3.2).
235: Control codes ``0'' and ``1'' are replaced in the output file
236: with ``\\n'' and ``\\f'' respectively.
237: The control character ``+'' is not implemented and, like
238: any other character in the first position of a record
239: written to a ``print'' file, is dropped.
240: .PP
241: An alternative is to use
242: the filter 'fpr'(1) for vertical format control.
243: It replaces ``0'' and ``1'' by
244: ``\\n'' and ``\\f'' respectively, and implements the ``+'' control code.
245: Unlike "form = 'print'"
246: which drops unrecognized form control characters, 'fpr' copies those
247: characters to the output file.
248: .PP
249: No vertical format control is recognized for
250: .B "direct formatted"
251: output or
252: .B "list directed"
253: output.
254: .Nh 2 "File names and the open statement"
255: A file name may be specified in an
256: .B open
257: statement for the
258: logical unit.
259: If a logical unit is opened by an
260: .B open
261: statement which does
262: not specify a file name, or it is opened implicitly by the execution
263: of a
264: .B read ,
265: .B write ,
266: .B backspace
267: or
268: .B rewind
269: statement, then the default file name is ``fort.N'' where N is
270: the logical unit number.
271: Before opening the file, the library checks for an environment
272: variable with a name identical to the tail of the
273: file name with periods removed.
274: If it finds such an environment variable, it uses its value
275: as the actual name of the file.
276: For example, a program containing:
277: .nf
278:
279: open(32,file="/usr/guest/census/data.d")
280: read(32,100) vec
281: write(44) vec
282:
283: .fi
284: normally will read from '/usr/guest/census/data.d' and write to
285: .B fort.44
286: in the current directory.
287: If the environment variables 'datad' and 'fort44' are set,
288: e.g.:
289: .nf
290:
291: % setenv datad mydata
292: % setenv fort44 myout
293:
294: .fi
295: in the C shell or:
296: .nf
297:
298: $ datad=mydata
299: $ fort44=myout
300: $ export datad fort44
301:
302: .fi
303: in the Bourne shell, then the program will read from 'mydata' and
304: write to 'myout'.
305: .PP
306: An
307: .B open
308: statement need not specify a file name. If it refers to a logical
309: unit that is already open, the
310: .B blank=
311: and
312: .B form=
313: specifiers may be
314: redefined without affecting the current file position.
315: Otherwise, if 'status = "scratch"'
316: is specified, a temporary file with a
317: name of the form ``tmp.FXXXXXX'' will be opened,
318: and, by default, will be deleted when closed or during
319: termination of program execution.
320: .PP
321: It is an error to try to open an existing file with 'status = "new"'.
322: It is an error to try to open a nonexistent file with 'status = "old"'.
323: By default, 'status = "unknown"'
324: will be assumed, and a file will be created if necessary.
325: .PP
326: By default, files are positioned
327: at their beginning upon opening, but see 'fseek'(3f)
328: and 'ioinit'(3f) for alternatives.
329: Existing files are never truncated on opening.
330: Sequentially accessed external files are truncated to the current file
331: position on
332: .B close ,
333: .B backspace
334: , or
335: .B rewind
336: only if the last
337: access to the file was a write.
338: An
339: .B endfile
340: always causes such files to be truncated to the current
341: file position.
342: .Nh 2 "Format interpretation"
343: Formats which are in format statements are parsed by the compiler;
344: formats in
345: .B read ,
346: .B write
347: , and
348: .B print
349: statements
350: are parsed during execution by the
351: .Sm I/O
352: library.
353: Upper as well as lower case characters are recognized in format statements
354: and all the alphabetic arguments to the I/O library routines.
355: .PP
356: If the external representation of a datum
357: is too large for the field width specified, the specified
358: field is filled with asterisks (\(**).
359: On
360: .B Ew.dEe
361: output,
362: the exponent field will be filled with asterisks if the
363: exponent representation is too large.
364: This will only happen if ``e'' is zero.
365: .PP
366: On output, a real value that is truly zero will display as ``0.'' to
367: distinguish it from a very small non-zero value.
368: If this causes problems for other input systems, the
369: .B BZ
370: edit descriptor may be used to cause the field
371: following the decimal point to be filled with zero's.
372: .PP
373: Non-destructive tabbing is implemented for both internal and external
374: formatted I/O.
375: Tabbing left or right on output
376: does not affect previously written portions of a record.
377: Tabbing right on output
378: causes unwritten portions of a record to be filled with blanks.
379: Tabbing right off the end of an input logical record is an error.
380: Tabbing left beyond the beginning of an input logical record leaves
381: the input pointer at the beginning of the record.
382: The format specifier
383: .B T
384: must be followed by a positive non-zero number.
385: If it is not, it will have a different meaning (see section 3.1).
386: .PP
387: Tabbing left requires seek ability on the logical unit.
388: Therefore it is not allowed in I/O to a terminal or pipe.
389: Likewise, nondestructive tabbing in either direction is possible
390: only on a unit that can seek. Otherwise tabbing right or spacing with
391: .B X
392: will write blanks on the output.
393: .Nh 2 "List directed output"
394: In formatting list directed output, the I/O system tries to prevent
395: output lines longer than 80 characters.
396: Each external datum will be separated by two spaces.
397: List-directed output of
398: .B complex
399: values includes an appropriate comma.
400: List-directed output distinguishes between
401: .B real
402: and
403: .B "double precision"
404: values and formats them differently.
405: Output of a character string that includes ``\\n''
406: is interpreted reasonably by the output system.
407: .Nh 2 "I/O errors"
408: If I/O errors are not trapped by the user's program an appropriate
409: error message will be written to ``stderr'' before aborting.
410: An error number will be printed in ``[ ]'' along with a brief error message
411: showing the logical unit and I/O state.
412: Error numbers < 100 refer to
413: .UX
414: errors, and are described in the
415: introduction to chapter 2 of the
416: .UX
417: Programmer's Manual.
418: Error numbers \(>= 100 come from the I/O library, and are described
419: on-line in "help f77 io_err_msgs".
420: For internal I/O, part of the string will be printed with ``|'' at the
421: current position in the string.
422: For external I/O, part of the current record will be displayed if
423: the error was caused during reading from a file that can backspace.
424: .sp 1
425: .Nh 1 "Non-``ANSI Standard'' extensions"
426: Several extensions have been added to the I/O system to provide
427: for functions omitted or poorly defined in the standard.
428: Programmers should be aware that these are non-portable.
429: .Nh 2 "Format specifiers"
430: .B B
431: is an acceptable edit control specifier. It causes return to the
432: default mode of blank interpretation.
433: This is consistent with
434: .B S
435: which returns to default sign control.
436: .PP
437: .B P
438: by itself is equivalent to
439: .B 0P .
440: It resets the scale factor to the
441: default value, 0.
442: .PP
443: The form of the
444: .B Ew.dEe
445: format specifier has been extended to
446: .B D
447: also.
448: The form
449: .B Ew.d.e
450: is allowed but is not standard.
451: The ``e'' field specifies the minimum number of digits or spaces in the
452: exponent field on output.
453: If the value of the exponent is too large, the exponent notation
454: .B e
455: or
456: .B d
457: will be dropped from the output to allow one
458: more character position.
459: If this is still not adequate, the ``e'' field will be filled with
460: asterisks (\(**).
461: The default value for ``e'' is 2.
462: .PP
463: An additional form of tab control specification has been added.
464: The
465: .Sm ANSI
466: standard forms 'TRn', 'TLn', and 'Tn' are supported
467: where 'n'
468: is a positive non-zero number.
469: If 'T' or 'nT' is specified, tabbing will
470: be to the next (or n-th) 8-column tab stop.
471: Thus columns of alphanumerics can be lined up without counting.
472: .PP
473: A format control specifier has been added to suppress the newline
474: at the end of the last record of a formatted sequential write. The
475: specifier is a dollar sign ($). It is constrained by the same rules
476: as the colon (:). It is used typically for console prompts.
477: For example:
478: .nf
479:
480: write (\(**, "(\(fmenter value for x: \(fm,$)")
481: read (\(**,\(**) x
482: .fi
483: .PP
484: Radices other than 10 can be specified for formatted integer I/O
485: conversion. The specifier is patterned after
486: .B P ,
487: the scale factor for
488: floating point conversion. It remains in effect until another radix is
489: specified or format interpretation is complete. The specifier is defined
490: as '[n]R' where 2 \(<= n \(<= 36. If
491: .I n
492: is omitted,
493: the default decimal radix is restored.
494: .PP
495: The format specifier 'Om.n' may be used for an octal conversion;
496: it is equivalent to '8R,Im.n,10R'.
497: Similarly, 'Zm.n' is equivalent to '16R,Im.n,10R' and
498: may be used for an hexadecimal conversion;
499: .PP
500: In conjunction with the above, a sign control specifier has been added
501: to cause integer values to be interpreted as unsigned during output
502: conversion. The specifier is
503: .B SU
504: and remains in effect until another
505: sign control specifier is encountered, or format interpretation is
506: complete.
507: Radix and ``unsigned'' specifiers could be used to format
508: a hexadecimal dump, as follows:
509:
510: .nf
511: 2000 format ( SU, 8Z10.8 )
512: .fi
513:
514: (Note: Unsigned integer values greater than (2\(**\(**31 - 1),
515: can be read and written using \fBSU\fP.
516: However they can not be used in
517: computations because
518: .Fo
519: uses signed arithmetic and such values appear to the arithmetic unit
520: as negative numbers.)
521: .Nh 2 "Print files"
522: The
523: .Sm ANSI
524: standard is ambiguous regarding the definition of a ``print'' file.
525: Since
526: .UX
527: has no default ``print'' file, an additional
528: .B form=
529: specifier
530: is now recognized in the
531: .B open
532: statement.
533: Specifying
534: .B "form = \(fmprint\(fm"
535: implies
536: .B formatted
537: and enables vertical format
538: control for that logical unit (see section 2.3).
539: Vertical format control is interpreted only on sequential formatted writes
540: to a ``print'' file.
541: .PP
542: The
543: .B inquire
544: statement will return
545: .B print
546: in the
547: .B form=
548: string variable
549: for logical units opened as ``print'' files.
550: It will return -1 for the unit number of an unconnected file.
551: .PP
552: If a logical unit is already open, an
553: .B open
554: statement including the
555: .B form=
556: option or the
557: .B blank=
558: option will do nothing but re-define those options.
559: This instance of the
560: .B open
561: statement need not include the file name, and
562: must not include a file name if
563: .B unit=
564: refers to a standard input or output.
565: Therefore, to re-define the standard output as a ``print'' file, use:
566: .nf
567:
568: open (unit=6, form=\(fmprint\(fm)
569: .fi
570: .Nh 2 "Scratch files"
571: A
572: .B close
573: statement with 'status = "keep"'
574: may be specified for temporary files.
575: This is the default for all other files.
576: Remember to get the scratch file's real name,
577: using
578: .B inquire ,
579: if you want to re-open it later.
580: .Nh 2 "List directed I/O"
581: List directed read has been modified to allow
582: tab characters wherever blanks are allowed.
583: It also allows input of a string not enclosed in quotes.
584: The string must not start with a digit or quote,
585: and can not contain any separators ( ``,'', ``/'', blank or tab ).
586: A newline will terminate the string unless escaped with \\.
587: Any string not meeting the above restrictions
588: must be enclosed in quotes (`` " '' or `` \(fm '').
589: .PP
590: Internal list-directed I/O has been implemented. During internal list reads,
591: bytes are consumed until the iolist is satisfied, or the ``end-of-file''
592: is reached.
593: During internal list writes, records are filled until the iolist is satisfied.
594: The length of an internal array element should be at least 20 bytes to
595: avoid logical record overflow when writing double precision values.
596: Internal list read was implemented to make command line decoding easier.
597: Internal list write should be avoided.
598: .sp 1
599: .Nh 1 "Running older programs"
600: Traditional
601: .Fo
602: environments usually assume carriage control on all logical units,
603: usually interpret blank spaces on input as ``0''s, and often provide
604: attachment of global file names to logical units at run time.
605: There are several routines in the I/O library to provide these functions.
606: .Nh 2 "Traditional unit control parameters"
607: If a program reads and writes only units 5 and 6, then including
608: .B \-lI66
609: in the f77 command will cause carriage control to be interpreted on
610: output and cause blanks to be zeros on input without further
611: modification of the program.
612: If this is not adequate,
613: the routine 'ioinit'(3f) can be called to specify control parameters
614: separately, including whether files should be positioned at their
615: beginning or end upon opening.
616: .Nh 2 "Ioinit()"
617: \&'Ioinit'(3f) can be used to attach logical units
618: to specific files at run time, and to set global parameters for the
619: .Sm I/O
620: system.
621: It will look for names of a user specified form in the environment
622: and open the corresponding logical unit for
623: .B "sequential formatted"
624: I/O.
625: Names must be of the form
626: .B PREFIXnn
627: where
628: .B PREFIX
629: is specified in the call to
630: .I ioinit
631: and
632: .I nn
633: is the logical unit to be opened. Unit numbers < 10 must include
634: the leading ``0''.
635: .PP
636: .I Ioinit
637: should prove adequate for most programs as written.
638: However, it
639: is written in
640: .Fo \-77
641: specifically so that it may serve as an example for similar
642: user-supplied routines.
643: A copy may be retrieved by ``ar x /usr/lib/libU77.a ioinit.f''.
644: See section 2.4 for another way to override program file names
645: through environment variables.
646: .sp 1
647: .Nh 1 "Magnetic tape I/O"
648: Because the I/O library uses stdio buffering, reading or writing
649: magnetic tapes should be done with great caution, or avoided if possible.
650: A set of routines has been provided to read and write arbitrary sized buffers
651: to or from tape directly. The buffer must be a
652: .B character
653: object.
654: .B Internal
655: I/O can be used to fill or interpret the buffer.
656: These routines do not use normal
657: .Fo
658: I/O processing and do not obey
659: .Fo
660: I/O rules.
661: See 'topen'(3f).
662: .sp 1
663: .Nh 1 "Caveat Programmer"
664: The I/O library is extremely complex yet we believe there are few bugs left.
665: We've tried to make the system as correct as possible according to
666: the
667: .Sm ANSI
668: X3.9\-1978 document and keep it compatible with the
669: .UX
670: file system.
671: .LP
672: .ce 1
673: Exceptions to the ANSI Standard
674: .sp 1
675: .PP
676: A few exceptions to the
677: .Sm ANSI
678: standard remain.
679: .LP
680: 1) Vertical format control
681: .PP
682: The ``+'' carriage control specifier is not fully implemented
683: (see section 2.3).
684: It would be difficult to implement it correctly and still
685: provide
686: .UX -like
687: file I/O.
688: .PP
689: Furthermore, the carriage control implementation is asymmetrical.
690: A file written with carriage control interpretation can not be
691: read again with the same characters in column 1.
692: .PP
693: An alternative to interpreting carriage control internally is to
694: run the output file through a ``Fortran output filter''
695: before printing. This filter could recognize a much broader range
696: of carriage control and include terminal dependent processing.
697: One such filter is 'fpr'(1).
698: .sp 1
699: .LP
700: 2) Default files
701: .PP
702: Files created by default use of
703: .B rewind
704: or
705: .B endfile
706: statements are opened for
707: .B "sequential formatted"
708: access. There is no way to redefine such a file to allow
709: .B direct
710: or
711: .B unformatted
712: access.
713: .sp 1
714: .LP
715: 3) Lower case strings
716: .PP
717: It is not clear if the
718: .Sm ANSI
719: standard requires internally generated strings to be upper case or not.
720: As currently written, the
721: .B inquire
722: statement will return lower case strings for any alphanumeric data.
723: .sp 1
724: .LP
725: 4) Exponent representation on Ew.dEe output
726: .PP
727: If the field width for the exponent is too small, the standard
728: allows dropping the exponent character but only if the exponent
729: is > 99. This system does not enforce that restriction.
730: Further, the standard implies that the entire field, `w', should be
731: filled with asterisks if the exponent can not be displayed.
732: This system fills only the exponent field in the above case since
733: that is more diagnostic.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.