1"use strict";(self.webpackChunkada_lang_io=self.webpackChunkada_lang_io||[]).push([["2267"],{29950(e,n,i){i.r(n),i.d(n,{metadata:()=>t,default:()=>u,frontMatter:()=>r,contentTitle:()=>l,toc:()=>d,assets:()=>o});var t=JSON.parse('{"id":"style-guide/s7/06","title":"7.6 Input/Output","description":"I/O facilities in Ada are not a part of the syntactic definition of the","source":"@site/docs/style-guide/s7/06.mdx","sourceDirName":"style-guide/s7","slug":"/style-guide/s7/06","permalink":"/docs/style-guide/s7/06","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"title":"7.6 Input/Output"},"sidebar":"styleGuideSidebar","previous":{"title":"7.5 Representation Clauses And Implementation-Dependent Features","permalink":"/docs/style-guide/s7/05"},"next":{"title":"7.7 Summary","permalink":"/docs/style-guide/s7/07"}}'),a=i(74848),s=i(28453);let r={title:"7.6 Input/Output"},l,o={},d=[{value:"Name and Form Parameters",id:"name-and-form-parameters",level:3},{value:"guideline",id:"guideline",level:4},{value:"rationale",id:"rationale",level:4},{value:"notes",id:"notes",level:4},{value:"File Closing",id:"file-closing",level:3},{value:"guideline",id:"guideline-1",level:4},{value:"rationale",id:"rationale-1",level:4},{value:"Input/Output on Access Types",id:"inputoutput-on-access-types",level:3},{value:"guideline",id:"guideline-2",level:4},{value:"rationale",id:"rationale-2",level:4},{value:"Package Ada.Streams.Stream_IO",id:"package-adastreamsstream_io",level:3},{value:"guideline",id:"guideline-3",level:4},{value:"rationale",id:"rationale-3",level:4},{value:"Current Error Files",id:"current-error-files",level:3},{value:"guideline",id:"guideline-4",level:4},{value:"example",id:"example",level:4},{value:"rationale",id:"rationale-4",level:4},{value:"notes",id:"notes-1",level:4}];function c(e){let n={a:"a",code:"code",h3:"h3",h4:"h4",li:"li",p:"p",pre:"pre",ul:"ul",...(0,s.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.p,{children:"I/O facilities in Ada are not a part of the syntactic definition of the\nlanguage. The constructs in the language have been used to define a set\nof packages for this purpose. These packages are not expected to meet\nall the I/O needs of all applications, in particular, embedded systems.\nThey serve as a core subset that may be used on straightforward data and\nthat can be used as examples of building I/O facilities upon the\nlow-level constructs provided by the language. Providing an I/O\ndefinition that could meet the requirements of all applications and\nintegrate with the many existing operating systems would result in\nunacceptable implementation dependencies. The types of portability\nproblems encountered with I/O tend to be different for applications\nrunning with a host operating system versus embedded targets where the\nAda run-time is self-sufficient. Interacting with a host operating\nsystem offers the added complexity of coexisting with the host file\nsystem structures (e.g., hierarchical directories), access methods\n(e.g., indexed sequential access method [ISAM]), and naming\nconventions (e.g., logical names and aliases based on the current\ndirectory). The section on Input/Output in ARTEWG (1986) provides some\nexamples of this kind of dependency. Embedded applications have\ndifferent dependencies that often tie them to the low-level details of\ntheir hardware devices."}),"\n",(0,a.jsx)(n.p,{children:"The major defense against these inherent implementation dependencies in\nI/O is to try to isolate their functionality in any given application.\nThe majority of the following guidelines are focused in this direction."}),"\n",(0,a.jsx)(n.h3,{id:"name-and-form-parameters",children:"Name and Form Parameters"}),"\n",(0,a.jsx)(n.h4,{id:"guideline",children:"guideline"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Use constants and variables as symbolic actuals for the Name and Form\nparameters on the predefined I/O packages. Declare and initialize them\nin an implementation dependency package."}),"\n"]}),"\n",(0,a.jsx)(n.h4,{id:"rationale",children:"rationale"}),"\n",(0,a.jsx)(n.p,{children:"The format and allowable values of these parameters on the predefined\nI/O packages can vary greatly between implementations. Isolation of\nthese values facilitates portability. Not specifying a Form string or\nusing a null value does not guarantee portability because the\nimplementation is free to specify defaults."}),"\n",(0,a.jsx)(n.h4,{id:"notes",children:"notes"}),"\n",(0,a.jsx)(n.p,{children:"It may be desirable to further abstract the I/O facilities by defining\nadditional Create and Open procedures that hide the visibility of the\nForm parameter entirely (see Pappas 1985, 54-55)."}),"\n",(0,a.jsx)(n.h3,{id:"file-closing",children:"File Closing"}),"\n",(0,a.jsx)(n.h4,{id:"guideline-1",children:"guideline"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Close all files explicitly."}),"\n"]}),"\n",(0,a.jsx)(n.h4,{id:"rationale-1",children:"rationale"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.a,{href:"/docs/arm/AA-A/AA-A.7",children:"Ada Reference Manual, \xa7A.7"})," does not define\nwhat happens to external files after completion of the main subprogram\n(in particular, if corresponding files have not been closed)."]}),"\n",(0,a.jsx)(n.p,{children:"The disposition of a closed temporary file may vary, perhaps affecting\nperformance and space availability (ARTEWG 1986)."}),"\n",(0,a.jsx)(n.h3,{id:"inputoutput-on-access-types",children:"Input/Output on Access Types"}),"\n",(0,a.jsx)(n.h4,{id:"guideline-2",children:"guideline"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Avoid performing I/O on access types."}),"\n"]}),"\n",(0,a.jsx)(n.h4,{id:"rationale-2",children:"rationale"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.a,{href:"/docs/arm/AA-A/AA-A.7",children:"Ada Reference Manual, \xa7A.7"})," does not\nspecify the effects of I/O on access types. When such a value is\nwritten, it is placed out of reach of the implementation. Thus, it is\nout of reach of the reliability-enhancing controls of strong type\nchecking."]}),"\n",(0,a.jsx)(n.p,{children:"Consider the meaning of this operation. One possible implementation of\nthe values of access types is virtual addresses. If you write such a\nvalue, how can you expect another program to read that value and make\nany sensible use of it? The value cannot be construed to refer to any\nmeaningful location within the reader's address space, nor can a reader\ninfer any information about the writer's address space from the value\nread. The latter is the same problem that the writer would have trying\nto interpret or use the value if it is read back in. To wit, a garbage\ncollection and/or heap compaction scheme may have moved the item\nformerly accessed by that value, leaving that value \"pointing\" at space\nthat is now being put to indeterminable uses by the underlying\nimplementation."}),"\n",(0,a.jsx)(n.h3,{id:"package-adastreamsstream_io",children:"Package Ada.Streams.Stream_IO"}),"\n",(0,a.jsx)(n.h4,{id:"guideline-3",children:"guideline"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Consider using Sequential_IO or Direct_IO instead of Stream_IO unless\nyou need the low-level, heterogeneous I/O features provided by\nStream_IO."}),"\n"]}),"\n",(0,a.jsx)(n.h4,{id:"rationale-3",children:"rationale"}),"\n",(0,a.jsx)(n.p,{children:"Sequential_IO and Direct_IO are still well suited for processing\nhomogeneous files. Additionally, in cases where the intent is to process\nhomogeneous files, the use of Sequential_IO or Direct_IO has the\nadvantage of enforcing this intent at compile time."}),"\n",(0,a.jsx)(n.p,{children:"Stream_IO should be reserved for processing heterogeneous files. In this\ncase, a file is not a sequence of objects of all the same type but\nrather a sequence of objects of varying types. To read a heterogeneous\nsequence of objects in the correct order requires some\napplication-specific knowledge."}),"\n",(0,a.jsx)(n.h3,{id:"current-error-files",children:"Current Error Files"}),"\n",(0,a.jsx)(n.h4,{id:"guideline-4",children:"guideline"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Consider using Current_Error and Set_Error for run-time error\nmessages."}),"\n"]}),"\n",(0,a.jsx)(n.h4,{id:"example",children:"example"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-ada",children:'with Ada.Text_IO;\n\n...\n\nbegin\n Ada.Text_IO.Open (File => Configuration_File,\n Mode => Ada.Text_IO.In_File,\n Name => Configuration_File_Name);\nexception\n when Ada.Text_IO.Name_Error =>\n Ada.Text_IO.Put_Line (File => Ada.Text_IO.Standard_Error,\n Item => "Can\'t open configuration file.");\n ...\nend;\n'})}),"\n",(0,a.jsx)(n.h4,{id:"rationale-4",children:"rationale"}),"\n",(0,a.jsx)(n.p,{children:"The package Text_IO includes the concept of a current error file. You\nshould report errors to the user through the associated subprograms\nCurrent_Error and Set_Error instead of the standard output facilities.\nIn interactive applications, using the Text_IO error facilities\nincreases the portability of your user interface."}),"\n",(0,a.jsx)(n.h4,{id:"notes-1",children:"notes"}),"\n",(0,a.jsx)(n.p,{children:'In a program with multiple tasks for I/O, you need to be careful of two\nor more tasks trying to set Current_Input, Current_Output, or\nCurrent_Error. The potential problem lies in unprotected updates to the\n"shared" state associated with a package, in this case, the package\nText_IO. Guidelines 6.1.1 and 6.2.4 discuss the related issues of\nunprotected shared variables.'})]})}function u(e={}){let{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(c,{...e})}):c(e)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.