![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to writeup CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 3BSD / new / libI77uc|
Return to writeup CVS log | Up to [CSRG BSD Unix] / 3BSD / new / libI77uc |
1.1 root 1:
2:
3:
4:
5:
6:
7:
8:
9:
10: Update to the f77 I/O Library
11: January 1980
12:
13:
14: David L. Wasley
15:
16: University of California
17: Berkeley, Calif. 94720
18:
19:
20:
21:
22:
23: The fortran-77 I/O library, libI77.a, has been exten-
24: sively updated. All known bugs have been fixed, and I/O
25: error reporting has been improved. Several non-standard
26: extensions to FORTRAN I/O have been added.
27:
28: Some general concepts regarding f77 I/O deserve clarif-
29: ication. There are three forms of I/O: formatted, unformat-
30: ted, and list-directed. The last is related to formatted but
31: does not obey all the rules for formatted I/O. There are
32: two modes of access to external and internal files: direct
33: and sequential. The definition of a logical record depends
34: upon the combination of I/O form and mode specified by the
35: fortran I/O statement.
36:
37: A logical record in direct access external files is a
38: string of bytes of a length specified when the file is
39: opened. Read and write statements must not specify logical
40: records longer than the original record size definition.
41: Shorter logical records are allowed. Unformatted direct
42: writes leave the unfilled part of the record undefined.
43: Formatted direct writes cause the unfilled record to be pad-
44: ded with blanks.
45:
46: Logical records in sequentially accessed external files
47: may be of arbitrary and variable length. Logical record
48: length for unformatted sequential files is determined by the
49: size of items in the iolist. For formatted write state-
50: ments, logical record length is determined by the format
51: statement interacting with the iolist at execution time.
52: Formatted sequential access causes one or more logical
53: records ending with 'newline' characters to be read or writ-
54: ten.
55:
56: Logical record length for list-directed I/O is rela-
57: tively meaningless. On output, the record length is depen-
58: dent on the magnitude of the data items. On input, the
59: record length is determined by the data types and the file
60: contents.
61:
62:
63:
64:
65:
66:
67:
68:
69:
70: - 2 -
71:
72:
73: The logical record length for "internal" files is the
74: length of the character variable or array element. Thus a
75: simple character variable is a single logical record. A
76: character variable array is similar to a fixed length direct
77: access file, and obeys the same rules. Unformatted I/O is
78: not allowed on "internal" files.
79:
80: Note that each execution of a fortran unformatted I/O
81: statement causes a single logical record to be read or writ-
82: ten. Each execution of a fortran formatted I/O statement
83: causes one or more logical records to be read or written.
84:
85: Any error detected during I/O processing will cause the
86: program to abort unless alternate action has been provided
87: for specifically in the program. Any I/O statement may
88: include an err= clause (and iostat= clause) to specify an
89: alternate branch to be taken on errors (and return the
90: specific error code). Read or write statements may include
91: end= to branch on end-of-file. File position and the value
92: of I/O list items is undefined following an error.
93:
94: I. Implementation details.
95:
96: The maximum number of logical units that a program may
97: have open at one time has been set to correspond with the
98: UNIX system limit, currently 20. However, the I/O library
99: uses UNIX file access for internal purposes. Therefore
100: fatal errors are possible if the maximum number of files are
101: open. Specifically, 'close' or 'endfile' on an old file,
102: and "'inquire' by file" may fail.
103:
104: Vertical format control is implemented. The logical
105: unit must be opened for sequential access and "form =
106: 'print'" (see below). Control codes '0' and '1' are
107: replaced in the output file with '\n' and '\f' respectively.
108: The control character '+' isn't implemented and, like any
109: other character in the first position of a record written to
110: a "print" file, is dropped. No vertical format control is
111: recognized for direct formatted output or list directed out-
112: put.
113:
114: Default logical units 0, 5, and 6 can be re-defined
115: with an 'open' statement. To preserve error reporting, it
116: is an error to close logical unit 0. If you want to open
117: the default filename for any preconnected logical unit,
118: remember to 'close' the unit first. Redefining the standard
119: units may impair normal console I/O. An alternative is to
120: use shell re-direction to externally re-define the above
121: units. To re-define default blank control or format of the
122: standard input or output files, use the 'open' statement
123: specifying the unit number and no filename (see below).
124:
125: An 'open' statement need not specify a filename. If it
126: refers to a logical unit that is already open, the "blank= "
127:
128:
129:
130:
131:
132:
133:
134:
135:
136: - 3 -
137:
138:
139: and "form= " specifiers may be redefined without affecting
140: the current file position. Otherwise, if "status='scratch'"
141: is specified, a temporary file with a name of the form
142: 'tmp.FXXXXXX' will be opened, and, by default, will be
143: deleted when closed or during termination of program execu-
144: tion. Any other "status= " specifier without an associated
145: filename results in opening a file named 'fort.N' where N is
146: the specified logical unit number. It is an error to try to
147: open an existing file with "status='new'". It is an error
148: to try to open a nonexistent file with "status='old'". By
149: default "status='unknown'" will be assumed, and a file will
150: be created if necessary. Existing files are never truncated
151: on opening but are positioned at the end-of-file.
152:
153: Sequentially accessed external files are truncated to
154: the current file position on 'close', 'backspace', or
155: 'rewind' only if the last access to the file was a write.
156:
157: Upper as well as lower case characters are recognized
158: in format statements and all alphabetic arguments to the I/O
159: library routines. This has always been true for statements
160: that are part of the source code, but not for format state-
161: ments or character arguments from a file.
162:
163: If the external representation of a datum is too large
164: for the field width specified, the specified field is filled
165: with asterisks (*). On 'Ew.dEe' output, the e field will be
166: filled with asterisks if the exponent representation is too
167: large. (This will only happen if e==0)
168:
169: List-directed output of complex values now includes an
170: appropriate comma. List-directed output now distinguishes
171: between real*4 and real*8 values and formats them dif-
172: ferently. Output of a character string that includes '\n'
173: now works correctly.
174:
175: If I/O errors are not trapped by the user's program an
176: appropriate error message will be written to 'stderr' before
177: aborting. An error number will be printed in [ ] along with
178: a brief error message showing the logical unit and I/O
179: state. Error numbers < 100 refer to UNIX errors, and are
180: described in the introduction to chapter 2 of the UNIX
181: Programmer's Manual. Error numbers >= 100 come from the I/O
182: library, and are described further in the appendix to this
183: writeup. For internal I/O, part of the string will be
184: printed with '|' at the current position in the string. For
185: external I/O, part of the current record will be displayed
186: if the error was caused during reading from a file that can
187: backspace.
188:
189: Direct access list-directed I/O is not allowed. Unfor-
190: matted internal I/O is not allowed. Both the above will be
191: caught by the compiler. All other flavors of I/O are
192: allowed, although some are not part of the ANSI standard.
193:
194:
195:
196:
197:
198:
199:
200:
201:
202: - 4 -
203:
204:
205: The standard units, 0, 5, and 6, are now named inter-
206: nally 'stderr', 'stdin', and 'stdout' respectively. These
207: are not actual filenames and can not be used for opening
208: these units. 'inquire' will not return these names and will
209: indicate that the above units are not named unless they have
210: been opened to real files. The names are meant to make
211: error reporting more meaningful.
212:
213: On output, a real value that is truly zero will display
214: as '0.' to distinguish it from a very small non-zero value.
215: This occurs in 'F', 'E', 'D', and 'G' format conversions.
216:
217: Non-destructive tabbing is implemented for both inter-
218: nal and external formatted I/O. Tabbing left or right on
219: output does not affect previously written portions of a
220: record. Tabbing right on output causes unwritten portions
221: of a record to be filled with blanks. Tabbing left or right
222: off the end of a logical record is an error. The format
223: specifier 'T' must be followed by a positive non-zero
224: number. If it is not, it will have a different meaning (See
225: below). Note that spacing with 'X' always writes blanks in
226: the output record.
227:
228: II. Non-"ANSI Standard" Extensions
229:
230: B is an acceptable edit control specifier. It causes
231: return to the default mode of blank interpretation (NULL)
232: and is identical to BN. This is consistent with S which
233: returns to default sign control.
234:
235: P by itself is equivalent to 0P. It resets the scale
236: factor to the default value, 0.
237:
238: The form of the 'Ew.dEe' format specifier has been
239: extended to 'D' also. The form 'Ew.d.e' is allowed but is
240: not standard. The 'e' field specifies the minimum number of
241: digits or spaces in the exponent field on output. If the
242: value of the exponent is too large, the exponent notation
243: 'e' or 'd' will be dropped from the output to allow one more
244: character position. If this is still not adequate, the 'e'
245: field will be filled with asterisks (*). The default value
246: for 'e' is 2.
247:
248: An additional form of tab control specification has
249: been added. The ANSI standard forms 'TRn', 'TLn', and 'Tn'
250: are supported where n is a positive non-zero number. If 'T'
251: or 'nT' is specified, tabbing will be to the next (or n-th)
252: 8-column tab stop. Thus columns of alphanumerics can be
253: lined up without counting. (See above for a description of
254: the tabbing implementation.)
255:
256: A format control specifier has been added to suppress
257: the newline at the end of the last record of a formatted
258: sequential write. The specifier is a dollar sign ($). It is
259:
260:
261:
262:
263:
264:
265:
266:
267:
268: - 5 -
269:
270:
271: constrained by the same rules as the colon (:). It is used
272: typically for console prompts. For example:
273:
274:
275: write (*, "('enter value for x: ',$)")
276: read (*,*) x
277:
278:
279: Radices other than 10 can be specified for formatted
280: integer I/O conversion. The specifier is patterned after P,
281: the pre-scale factor for floating point conversion. It
282: remains in effect until another radix is specified or format
283: interpretation is complete. The specifier is defined as [n]R
284: where 2 <= n <= 36. If n is omitted, the default decimal
285: radix is restored.
286:
287: In conjunction with the above, a sign control specifier
288: has been added to cause integer values to be interpreted as
289: unsigned during output conversion. The specifier is SU and
290: remains in effect until another sign control specifier is
291: encountered, or format interpretation is complete. Radix and
292: 'unsigned' specifiers could be used to format a hexadecimal
293: dump, as follows:
294:
295:
296: 2000 format( SU, 16R, 8I10.8)
297:
298:
299: Note: Unsigned integer values greater than (2**30 - 1), i.e.
300: any signed negative value, can not be read by FORTRAN input
301: routines. All internal values will be output correctly.
302:
303: The ANSI standard is ambiguous regarding the definition
304: of a "print" file. Since UNIX has no default "print" file,
305: an additional 'form' specifier is now recognized in the
306: 'open' statement. Specifying "form='print'" implies 'for-
307: matted' and enables vertical format control for that logical
308: unit (see above). Vertical format control is interpreted
309: only on sequential formatted writes to a "print" file.
310:
311: The 'inquire' statement will return 'print' in the
312: 'FORM=' string variable for logical units opened as "print"
313: files. It will return -1 for the unit number of an uncon-
314: nected file.
315:
316: If a logical unit is already open, an 'open' statement
317: including the re-define those options. This instance of the
318: 'open' statement need not include the filename, and must not
319: include a filename if 'unit=' refers to the standard input
320: or outputs. Therefore, to re-define the standard output as
321: a "print" file, use:
322:
323:
324: open (unit=6, form='print')
325:
326:
327:
328:
329:
330:
331:
332:
333:
334: - 6 -
335:
336:
337: In a 'close' statement, "status='keep'" may be speci-
338: fied for temporary files. This is the default for all other
339: files. Remember to get the file's real name, using
340: 'inquire', if you want to re-open it later.
341:
342: List directed read has been modified to allow input of
343: a string not enclosed in quotes. The string must not start
344: with a digit, and can not contain a separator (, or /) or
345: blank (space or tab). A newline will terminate the string
346: unless escaped with \. Any string not meeting the above res-
347: trictions must be enclosed in quotes (" or ').
348:
349: Internal list-directed I/O has been implemented. During
350: internal list reads, bytes are consummed until the iolist is
351: satisfied, or the 'end-of-file' is reached. During internal
352: list writes, records are filled until the iolist is satis-
353: fied. The length of an internal array element should be at
354: least 20 bytes to avoid logical record overflow when writing
355: double precision values. Internal list read was implemented
356: to make command line decoding easier. Internal list write
357: should be avoided.
358:
359:
360:
361:
362:
363:
364:
365:
366:
367:
368:
369:
370:
371:
372:
373:
374:
375:
376:
377:
378:
379:
380:
381:
382:
383:
384:
385:
386:
387:
388:
389:
390:
391:
392:
393:
394:
395:
396:
397:
398:
399:
400: - 7 -
401:
402:
403: Appendix A
404: I/O Library Error Messages
405:
406: The following error messages are generated by the I/O
407: library. The error numbers are returned in the "iostat="
408: variable if the "err=" return is taken. Error numbers < 100
409: are generated by UNIX. See the UNIX Programmers Manual,
410: introduction to chapter 2.
411:
412: /* 100 */ "error in format"
413: See error message output for the location
414: of the error in the format. Can be caused
415: by more than 10 levels of nested (), or
416: an extremely long format statement.
417:
418: /* 101 */ "illegal unit number"
419: It is illegal to close logical unit 0.
420: Negative unit numbers are not allowed.
421: The upper limit is system dependent.
422:
423: /* 102 */ "formatted io not allowed"
424: The logical unit was opened for
425: unformatted I/O.
426:
427: /* 103 */ "unformatted io not allowed"
428: The logical unit was opened for
429: formatted I/O.
430:
431: /* 104 */ "direct io not allowed"
432: The logical unit was opened for sequential
433: access, or the logical record length was
434: specified as 0.
435:
436: /* 105 */ "sequential io not allowed"
437: The logical unit was opened for direct
438: access I/O.
439:
440: /* 106 */ "can't backspace file"
441: The file associated with the logical unit
442: can't seek. May be a device or a pipe.
443:
444: /* 107 */ "off beginning of record"
445: The format specified a left tab off the
446: beginning of the record.
447:
448: /* 108 */ "can't stat file"
449: The system can't return status information
450: about the file. Perhaps the directory is
451: unreadable.
452:
453: /* 109 */ "no * after repeat count"
454: Repeat counts in list-directed I/O must be
455: followed by an * with no blank spaces.
456:
457:
458:
459:
460:
461:
462:
463:
464:
465:
466: - 8 -
467:
468:
469: /* 110 */ "off end of record"
470: A formatted write tried to go beyond the
471: logical end-of-record. An unformatted read
472: or write will also cause this.
473:
474: /* 111 */ "truncation failed"
475: The truncation of external sequential files
476: on 'close', 'backspace', or 'rewind' tries
477: to do a copy. It failed. Perhaps the temp
478: file couldn't be created.
479:
480: /* 112 */ "incomprehensible list input"
481: List input has to be just right.
482:
483: /* 113 */ "out of free space"
484: The library dynamically creates buffers for
485: internal use. You ran out of memory for this.
486: Your program is too big!
487:
488: /* 114 */ "unit not connected"
489: The logical unit was not open.
490:
491: /* 115 */ "read unexpected character"
492: Certain format conversions can't tolerate
493: non-numeric data. Logical data must be
494: T or F.
495:
496: /* 116 */ "blank logical input field"
497:
498: /* 117 */ "'new' file exists"
499: You tried to open an existing file with
500: "status='new'".
501:
502: /* 118 */ "can't find 'old' file"
503: You tried to open a non-existent file
504: with "status='old'".
505:
506: /* 119 */ "unknown system error"
507: Shouldn't happen, but .....
508: (Send me a documented example.)
509:
510: /* 120 */ "requires seek ability"
511: Direct access requires seek ability.
512: Sequential unformatted I/O requires seek
513: ability on the file due to the special
514: data structure required. Tabbing left
515: also requires seek ability.
516:
517: /* 121 */ "illegal argument"
518: Certain arguments to 'open', etc. will be
519: checked for legitimacy. Often only non-
520: default forms are looked for.
521:
522:
523:
524:
525:
526:
527:
528:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.