ANSI IEEE 1003.26-2003 Information Technology - Portable Operating System Interface (POSIX)- Part 26 Device Control Application Program Interface (API) [C Language] (IEEE Computer .pdf

1、IEEE Std 1003.26-2003IEEE Standards1003.26TMIEEE Standard for Information Technology Portable Operating System Interface (POSIX) Part 26: Device Control Application Program Interface (API) C Language3 Park Avenue, New York, NY 10016-5997, USAIEEE Computer SocietySponsored by thePortable Applications

2、 Standards CommitteeIEEE Standards9 September 2004Print: SH95190PDF: SS95190Copyright 1998 IEEE All Rights Reserved 1IEEE Std 1003.26-2003(R2010)IEEE Standard for Information TechnologyPortable Operating System Interface (POSIX)Part 26: Device Control Application Program Interface (API) C LanguageSp

3、onsorPortable Applications Standards Committeeof theIEEE Computer SocietyApproved 26 April 2004American National Standards InstituteApproved 10 December 2003Reaffirmed 17 June 2010IEEE-SA Standards BoardAbstract: This standard is part of the POSIX series of standards. It defines an application progr

4、aminterface for controlling device drivers. Although it is based on the widely used ioctl() system call, theinterface is type-safe and has a fixed number of parameters.Keywords: API, application portability, C (programming language), data processing, informationinterchange, open systems, operating s

5、ystem, portable application, POSIX, programming language,realtime, device driversThe Institute of Electrical and Electronics Engineers, Inc.3 Park Avenue, New York, NY 10016-5997, USACopyright 2004 by the Institute of Electrical and Electronics Engineers, Inc.Abstract: This standard is part of the P

6、OSIX series of standards. It defines an applicationprogram interface for controlling device drivers. Although it is based on the widely used ioctl()system call, the interface is type-safe and has a fixed number of parameters.Keywords: API, application portability, C (programming language), data proc

7、essing, informa-tion interchange, open systems, operating system, portable application, POSIX, programminglanguage, realtime, device driversBSD is a trademark of the University of California, Berkeley, CA, USA.POSIX is a registered trademark of the Institute of Electrical and Electronics Engineers,

8、Inc.UNIX is a registered trademark of The Open Group.The Institute of Electrical and Electronics Engineers, Inc.3 Park Avenue, New York, NY 10016-5997, USACopyright 2004 by the Institute of Electrical and Electronics Engineers, Inc.All rights reserved. Published 09 September 2004. Printed in the Uni

9、ted States of America.IEEE is a registered trademark in the U.S. Patent (978) 750-8400. Permission to photocopy portions of any individual standard for educationalclassroom use can also be obtained through the Copyright Clearance Center.Note: Attention is called to the possibility that implementatio

10、n of this standard may require use of subject mat-ter covered by patent rights. By publication of this standard, no position is taken with respect to the existence orvalidity of any patent rights in connection therewith. The IEEE shall not be responsible for identifying patentsfor which a license ma

11、y be required by an IEEE standard or for conducting inquiries into the legal validity orscope of those patents that are brought to its attention.ivCopyright 2004 IEEE. All rights reserved.ContentsPAGEIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12、 . . . . . . . . . . . viSection 1: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Conformance . . . . . . . . . .

13、. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.1 Implementation Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.2 Application Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.3 Other Language-Relat

14、ed Specifications . . . . . . . . . . . . . . . . . . . . . . . 5Section 2: Normative References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1 Normative References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Section 3: Defini

15、tions and General Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.1 General Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.1.1 Special Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16、 . . 93.1.2 Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.2 C Language Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.2.1 POSIX.26 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . .

17、. . . . . . . . . . . . . 103.2.2 The Name Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Section 4: Conventions and Abbreviations . . . . . . .

18、. . . . . . . . . . . . . . . . . . . . . . . 134.1 Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.2 Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Section 5: Device Control .

19、 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.1 Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.1.1 Control a Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

20、 . . . . 15Annex A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19A.1 Related Open Systems Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19A.2 Other Documents . . . . . . . . . . . . . . . . . . . . . . . . .

21、. . . . . . . . . . . . . . . . . . 20Annex B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21B.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21B.2 Existing Practice. . .

22、. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22B.3 Relationship to ioctl() and the Perceived Needs for Improvement. . . . . 22B.4 Which Differences Between posix_devctl() and ioctl() Are Acceptable?. 24B.5 Rationale for the dev_info_ptr . . . . . . . . . . . . .

23、. . . . . . . . . . . . . . . . . . . . 24B.6 Rationale for No direction Argument . . . . . . . . . . . . . . . . . . . . . . . . . . . 25vCopyright 2004 IEEE. All rights reserved.B.7 Rationale for Not Defining the Direction Encoding in the command Word . . . . . . . . . . . . . . . . . . . . . . .

24、. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25B.8 Recommended Practice for Handling Data Size Errors . . . . . . . . . . . . . 26B.9 Recommended Practice for nbyte= 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . 26B.10 Recommended Practice for Driver-Detected Error

25、s . . . . . . . . . . . . . . . . 27Alphabetic Topical Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29vi IntroductionCopyright 2004 IEEE. All rights reserved.Introduction(This introduction is not a normative part of IEEE Std 1003.26-2003, IEEE Standa

26、rd forInformation TechnologyPortable Operating System Interface (POSIX)Part 26: Device ControlApplication Program Interface (API) C Language.)This standard defines systems interfaces to support the source portability ofapplications with realtime requirements and requiring in addition the control ofs

27、pecial devices. The system interfaces are all extensions of, or additions to, ISO/IEC 9945:2003 2 (identical to IEEE Std 1003.1-2003).Within this standard, the term “POSIX.1 2” refers to ISO/IEC 9945:2003 2.Realtime systems interact with their physical environment using a variety ofdevices (such as

28、analog-digital converters, digital-analog converters, counters, andvideo graphic equipment), which provide a set of services that cannot be fullyutilized in terms of read and/or write semantics. Traditional practice uses a singlefunction, called ioctl(), to encapsulate all the control operations on

29、the differentdevices connected to the system, both special or common devices. Developers ofPOSIX.1 2 decided not to standardize this interface because it was not type safe,it had a variable number of parameters, and it had behaviors that could not bespecified by the standard because they were driver

30、-dependent. Instead, POSIX.12 defined a device-specific application program interface (API) for a common classof drivers, Terminals; and it restricted the ioctl() function to control of STREAMSdevices.Although the POSIX.1 solution for common classes of devices is the best from thepoint of view of ap

31、plication portability, there is still a need for a way to interactwith special, or even common devices, for which developing a full standard API isnot practical. This standard defines a general method for interfacing to the widestpossible range of devices, through a new service to pass control infor

32、mation andcommands between the application and the device drivers.A driver for a special device will normally not be portable between systemimplementations, but an application that uses such a driver can be made portableif all functions calling the driver are well defined and standardized. Users and

33、integrators of realtime systems often add drivers for special devices, and astandardized function format for interfacing with these devices greatly simplifiesthis process.This standard has been defined exclusively at the source code level, for the Cprogramming language. Although the interfaces will

34、be portable, some of theparameters used by an implementation may have hardware or configurationdependencies.Introduction viiCopyright 2004 IEEE. All rights reserved.Organization of This StandardThis standard is divided into the following elements:(1) Statement of scope and overview (1)(2) List of no

35、rmative references (2)(3) Definitions and global concepts (3)(4) Conventions and abbreviations (4)(5) The various interface facilities (5)(6) Informative annexes containing the bibliography and rationaleThe C language binding for the service interface is given in the subclause labeledSynopsis (see 5

36、.1.1.1). The Description subclause (see 5.1.1.2) provides aspecification of the operation performed by the service interface. Some examplesmay be provided to illustrate the interfaces described.In most cases, there are also Returns and Errors subclauses specifying returnvalues and possible error con

37、ditions. References are used to direct the reader toother related sections. Additional material to complement sections in this standardmay be found in Annex B. This annex provides historical perspectives into thetechnical choices made by the developers of this standard. It also providesinformation t

38、o emphasize consequences of the interfaces described in thecorresponding section.Informative annexes are not part of the standard and are provided for informationonly. They are provided for guidance and help in understanding. (There is a typeof annex called normative that is part of a standard and i

39、mposes requirements, butthere are no such normative annexes in this standard.) BackgroundThe developers of POSIX standards represent a cross section of hardwaremanufacturers, vendors of operating systems and other software developmenttools, software designers, consultants, academics, authors, applic

40、ationsprogrammers, and others. In the course of their deliberations, the developersreviewed related American and international standards, both published and inprogress. Conceptually, the POSIX base standards describe a set of fundamental servicesneeded for the efficient construction of application p

41、rograms. Access to theseservices has been provided by defining APIs, using the C programming language,that establish standard semantics and syntax. The goal of these interfaces is toenable application writers to write portable applications.viii IntroductionCopyright 2004 IEEE. All rights reserved.Al

42、though originated to refer to IEEE Std 1003.1, the name POSIX more correctlyrefers to a family of related standards; namely, the IEEE 1003 series andInternational Standard ISO/IEC 9945. This standard belongs to the POSIX family.AudienceThe intended audience for this standard is the same as for ISO/I

43、EC 9945: allpersons concerned with an industry-wide standard operating system based on theUNIX1)system. This includes at least four groups of people:(1) Persons buying hardware and software systems,(2) Persons managing companies that are deciding on future corporate comput-ing directions,(3) Persons

44、 implementing operating systems, and especially(4) Persons developing applications where portability is an objective.PurposeSeveral principles guided the development of the POSIX standards in general andof this standard in particular.Application-OrientedThe basic goal was to promote portability of a

45、pplication programs acrossUNIX system environments by developing a clear, consistent, and unam-biguous standard for the interface specification of a portable operating sys-tem based on the UNIX system documentation. Interface, Not ImplementationThe POSIX standards define an interface, not an impleme

46、ntation. No dis-tinction is made between library functions and system calls: both arereferred to as functions. No details of the implementation of any functionare given (although historical practice is sometimes indicated in Annex B).Symbolic names are given for constants (such as signals and error

47、num-bers) rather than numbers.1) UNIX is a registered trademark of The Open Group.Introduction ixCopyright 2004 IEEE. All rights reserved.Source, Not Object, PortabilityThe POSIX standards have been written so that a program written andtranslated for execution on one conforming implementation may al

48、so betranslated for execution on another conforming implementation. In thisstandard, source code portability is limited to systems having the samespecial device drivers; but, if that is not the case, use of this standard willenhance portability by making the unportable parts that access specialdevic

49、es highly visible and uniformly used. This standard does not guaran-tee that executable (object or binary) code will execute under a conformingimplementation other than that for which it was translated, even if theunderlying hardware is identical.The C LanguageThis standard is written in terms of the standard C language as specifiedin ISO/IEC 9899:1999 1.No Superuser, No System AdministrationThere was no intention to specify all aspects of an operating system. Sys-tem administration facilities and functions are excluded from the POSIXbase stan