![[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 / libI77|
Return to writeup.tx CVS log | Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / usr.lib / libI77 |
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.