Introduction to OS APIs

Modular Structure of Software

The larger a computer program (measured in "lines of code") the more difficult it is for the programmer to keep the entire program in mind at once, and therefore the more difficult it is to avoid mistakes. There are two techniques for successfully writing large programs:

1. Use a language that accomplishes more per "line of code."

   This has driven the evolution of programming languages from the original machine language to assembly language to "higher-level" programming languages (Admiral Grace Hopper's work inventing COBOL being among the first), and still later to so-called "third-generation" and "fourth-generation" programming environments.

2. Program in functional modules, each of which is small enough for a person to grasp.
   • This works well if care is taken to limit the interactions between the functional modules, so that most of the code in each module can be considered in isolation.

   • This method also permits much more effective teamwork, because each individual programmer can work on one module, while other programmers work on other modules.

   • This approach emphasizes the value of analysis at the start of a programming project, breaking the tasks to be accomplished by the software into the appropriate modules.

   • For example, the operating system VMS contains over 64,000 modules with an aggregate total of over 50 million lines of source code, written in a dozen or more different languages.

Interaction Between Modules

There are several different ways in which a supposedly modular program can still be very difficult for a programmer to cope with:

Which modules invoke which other modules?

One way to visualize this is to create an overall dependency diagram with a block for each module and an arrow from each module to every other module that it invokes. If suitable placement of the blocks on the paper can result in none of these lines crossing each other, it will obviously be an easier program to keep straight in your mind than if the simplest possible arrangement resembles a spider web!

What are the possible sequences of execution of the various modules?

If there is only one possible sequence, so that module B is always invoked immediately after module A and immediately before module C, etc., it is much easier to grasp the program than if the sequence depends on user action, with some modules being executed repeatedly and others rarely or not even at all on some occasions when the program is used.

What are the methods by which information passes between modules?

Many programming languages provide specific mechanisms for passing information between modules, such a "arguments" or "parameters," "environment variables," "return values," "common blocks," and so on. Some programming languages require data variables to be shared among modules, some prevent it, and some permit it under programmer control.

The more different ways there are for information used by one module to be changed by the action of another module, the more difficult it is for the programmer to avoid mistakes.

Local and Global Scope of Variables

• A "global variable" can be used or modified by code in any module.

• A "local variable" can be used or modified only by the one module it is part of.

• If the programmer has used global variables and has chosen variable names for one or more of them that are similar to variables that are used only within a particular module, then we have the possibility of a particularly nasty bug: in one place where the programmer intended to use a global variable, a typographical error might result in having used a local variable, or vice versa, where a local variable was intended, a global one might have been used by mistake.

• The compiler cannot catch this logic mistake, because all the program statements are legal, they just do not have the intended effects!

  The probability of such mistakes can be reduced by programming according to conventions about variable names, but any use of global variables makes it more difficult to keep the programming task within the grasp of an individual programmer.

• Good practice for large software projects calls for the modules to use local variables and to communicate by arguments and return values.

Arguments and Return Values

• The code that starts execution of a module can also provide initial values for one or more specific local variables. These variables are known as the "arguments" of the module.

  For example, the code that invokes the module might be

  JDAY = JULIAN(YEAR,MONTH,DAY)

  where the module JULIAN takes the particular values given to it for the arguments, YEAR, MONTH, and DAY, and uses them to calculate the number of days since the Julian calendar's base date.

• When modules complete their work, information can be returned to the module that invoked them.
  • One numerical value may be returned. In the example above, JDAY is assigned a value by the module JULIAN, based on the input values in the arguments.

  • Multiple values may be returned by letting specified arguments pass data out of a module.

  • Multiple values may be returned by permitting one or more arguments to pass data both into and out of the module.

• Some programming languages support more than one of these mechanisms. Some permit the programmer to specify which mechanisms are available.

Operating System Services

• Software developers have demonstrated that many different programs can take advantage of a number of similar modules.

  For example, word processors, spreadsheets, presentation software, and database software, although they accomplish quite different tasks, all need to be able to permit the user to save work in progress into a data file, with the user being able to select the disk drive, folder name, file name, and in some cases file format.

  Every version of the Macintosh OS and every version of Windows has included, as part of the operating system, a module that provides that functionality.

• Software developers writing application programs do not have to write their own module that performs such functions. Instead, they write their software to use the operating system's module.

• Some operating systems provide modules that support graphical user interfaces, other operating systems provide modules that support command line user interfaces, some provide both.

Application Programming Interfaces

• Application Programming Interfaces (APIs, for short) are the specifications of the operating system modules that are intended to be used by people developing application software.

• Often they will also be used by some of the utility programs that are provided with the operating system, or for the internal functions of the operating system.

• By definition, APIs must include a description of the functions accomplished by the module and the mechanisms used to pass information into and back from the module. Typically this will include specification of
  • the number and order of the arguments;

  • for each argument, the type of variable (e.g., a text character, an integer stored with sign in 32 bits, an array of 100 floating point numbers stored in IEEE 64-bit format, etc.);

  • for each argument, whether the information is copied into the argument ("passed by value") or whether the argument contains the address in memory where the information is stored ("passed by reference");

  • for each argument, whether the argument passes information into the module, out of the module, or both;

  and so on.

Undocumented Modules

• Operating systems always include modules that are not documented as APIs. Modules may be undocumented because
  • the operating system developers do not believe those modules will be useful to application software developers, or

  • the operating system developers are not sure that the current form of those modules is the best design.

• Once an API is published, the operating system developers will be obliged to keep it working in all future versions of that operating system.

• Conspiracy theorists believe that another reason for undocumented operating system modules in Windows is to permit Microsoft applications (such as Office) to be "better" than applications from other software vendors (such as Lotus or Corel), who must use only the documented modules, in order to be sure that their software will continue to function in future versions of Windows.

Trusting vs. Careful Code Design

• When a module is invoked, one of the first things it may do is to verify that its arguments appear to be proper.

  For example, if one argument is supposed to be a file name, the code could check to see whether it contains any characters that are not legal to be parts of a filename in that operating system, whether it contains too many characters to be a legal file name, etc.

• Such careful code will make it easier to identify mistakes in the code that invokes the module.

• It will also make the program run more slowly and occupy more memory.

• Windows (all versions, including NT) is notorious for the absence of such careful design.

• This is partly a result of the fact that so much competition in the PC industry revolves around system performance.

• User-entered data that has unfortunate values and bugs in the application software can both result in internal operating system data or module code being corrupted. Sometimes this will simply result in the system freezing or crashing. Other times it will result in bad data being written to disk, where it will come back to haunt the user at some later time.

  The recently discovered bugs in Eudora, Netscape Communicator, and Microsoft Outlook, in which the filename of an E-mail attachment was not checked for length before the name was copied into system RAM, is an example of a vulnerability resulting from excessively trusting code design.

Notes

J. M. Fenster, 1998, "Amazing Grace." American Heritage of Invention & Technology, Fall, 1998, Volume 14, Number 2, pages 24-31.

Return to MIS 300 Page

Please E-Mail comments or suggestions to "piccard@ohio.edu".

© Copyright 1998 Richard D. Piccard