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