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