Multics Technical Bulletin                                MTB-691
Multics C Exe. Env. Spec.

To:       Distribution

From:     Douglas Howe

Date:     27 November 1985

Subject:  Multics C Execution Environment Specification

1.  Abstract

This MTB describes the execution environment that will be used by
C programs.  In this environment,  C programs and programmers can
limit the amount of interpretation to be done by Multics.

Changes will be marked with change bars.                          |

Comments should be sent to the authors:

     via Multics mail to:

        DGHowe.Multics

     via posted mail to:

        Douglas G.  Howe
        Advanced Computing Technology Centre
        Foothills Professional Building
        1620 29th St., N.W.
        Calgary Alberta Canada   T2N-4L7

     via telephone to:

        (403)-270-5400
        (403)-270-5437 (Howe)

     via forum on System-M to:

        >udd>m>DGHowe>mtgs_dir>c>c_imp (c)

_________________________________________________________________

Multics project  internal documentation; not to  be reproduced or
distributed outside the Multics project.


MTB-691                                Multics Technical Bulletin
                                        Multics C Exe. Env. Spec.

                        TABLE OF CONTENTS

Section    Page  Subject
=======    ====  =======

1          i     Abstract
2          1     Preface
3          2     Introduction
3.1        2     . . Goal
3.2        3     . . References For This Document
4          4     Background
5          6     Link Editor
5.1        6     . . Similarities With The Binder
5.2        6     . . Extensions From The Binder
6          7     `Main_'
6.1        7     . . Cleanup and Abort Handlers
6.2        8     . . Heap      and     Execution      Environment
                 Initialization
6.3        8     . . Convert Argc and Argv
6.4        8     . . Initialize I/O Structures
6.5        8     . . Call main
6.6        9     . . Cleanup of Space and Files
6.7        9     . . Reset Execution Environment


Multics Technical Bulletin                                MTB-691
Multics C Exe. Env. Spec.

2.  Preface

This document defines the execution  environment that C will have
on Multics.  Most of the  documentation needed to implement the C
compiler  on Multics  will be  supplied by  this MTB,  along with
MTB-647 and the other related MTBs.

We wish to thank those people  who have made this possible either
by  creating  tools  for  analysis  or  through  input of subject
matter.  These  people are Ron  Barstad, Greg Baryza,  Rick Gray,
Steve Herbst,  Dave Mason, Audrey  Neal, Tom Oke,  Doug Robinson,
Melanie Weaver and Brian Westcott.


MTB-691                                Multics Technical Bulletin
                                        Multics C Exe. Env. Spec.

3.  Introduction

This  Mtb describes  the execution  environment that  C will  use
under on Multics.  Although C programs on Multics will execute in
the standard Multics execution  environment, the environment will
have  a  few  extentions  to  allow  it  to  be  similar  to  the
environment  that C  programs and  programmers expect  for the  C
language.  C will be compatible with all the usual tools, such as
profile and trace,  and will be able to use  the system debugging
tools.

3.1.  Goal

The  goal  of  this  project  is  to  create  a  Multics native C
compiler.   Our objective  is to  allow the  porting of  existing
software  to Multics  and the  use of  basic Multics  tools.  The
compiler  is to  be  consistent  with Multics  compiler products,
while not losing compatibility with System V Release 2.0 C.(1)

The  product produced  by this  project, while  following Multics
standards, will introduce a new idea to Multics.  This idea is to
create an  environment in which  third party software  groups can
port their software without having to Multicize it.  This will be
done  by  the  introduction  of  a  linked  environment where the
possibility of dynamic linking can be limited to a specific group
of routines.

_________________________________________________________________

(1) Unix and System V Release 2.0 are registered trademarks of AT
    & T


Multics Technical Bulletin                                MTB-691
Multics C Exe. Env. Spec.

3.2.  References For This Document

1) MTB-647 created by Greg Baryza.

2) The C Programming Language
   Kernighan, Brian W.  & Ritchie, Dennis M.
   Prentice-Hall (1978)
   Englewood Cliffs, New Jersey

4) Multics Programmers Reference Manual (10.2 AG91-03A)
   (hereafter referred to as MPRM)

5) MTB 689 titled The C Runtime System on Multics by Doug Howe

6) MTB 688  titled The Multics C  Implementation Specification by
   Doug Howe.

7) MTB  entitled the  Multics Link  Editor Specification  by Dean
   Elhard and Doug Howe.


MTB-691                                Multics Technical Bulletin
                                        Multics C Exe. Env. Spec.

4.  Background

In  the development  of the  C language  on Multics  a series  of
environemntal dependancies  have become apparent.  Some  of these
dependancies are:

1)  Programs are  completely contained  in load  modules prior to
execution.  All  references to C's external  and static variables
are resolved prior to execution via a link editor or by compiling
module dependencies together creating  a self contained execution
structure.  Multics is  one of the few systems  that uses dynamic
linking.

2) All  external initialization is done prior  to referencing the
external items, and pertains only  to the current execution unit.
All of  C's heap allocations are on  a per-execution-process, not
on   a  per-login-process.    Most  other   systems  work   on  a
per-execution-process  rather than the  Multics per-login-process
environment.

3) All functions  in C (unless defined as  static) are considered
to be external.

4)  A C  execution unit  is entered  through an  entrypoint named
`main'.   All  other  functions  within  the  execution  unit are
considered to be unavailable from the system level.

5)  The  arguments  passed  to  main  programs  from  the command
processor are expected to be in a defined format.  This format is
defined  in two  variables passed  to programs  called 'Argc' and
'Argv'.  Argc contains the number  of parameters contained in the
command  processors argument list,  and Argv is  a pointer to  an
array  of pointers  to the   character strings  contained in  the
command line  terminated with the  null character.  The  value of
Argv[0] is  a pointer to  the name used  to enter the  routine at
command level.

6) C has no internal structure  that is defined to be a character
string.   So called  character strings  are arrays  of characters
terminated  with a  null  character.   These structures  are user
defined.

7) C's  normal environment ensures  the resetting of  storage and
the environment on exit from a program.


Multics Technical Bulletin                                MTB-691
Multics C Exe. Env. Spec.

Most C users expect to write their program, compile it, link edit
it with  a library and  execute it.  The  equivalent mechanism on
Multics includes the coordinated use of run units and the Multics
binder.  The  current binder while  being a general  Multics tool
does not  produce relocatable output  nor does it  allow a simple
user  interface similar  to what  is available  on other systems.
The  current binder can  not be altered  to use VLO's  and remain
compatable with  ealier versions.  To allow the  binder to remain
in its current form we will be  introducing a new user tool to be
named "The Multics Linkage Editor".

Run  units  are  currently   used  to  encapsulate  an  execution
environment   allowing  users    to  initialize   their  external
references with set_fortran_common and  it gives them the ability
to have an epiloge handler to clean up their environment by doing
such things as  closing opened files.  The run  unit mechanism is
unfortunately   set  up   to  operate   on  a   per-login-process
environment.  Run units do allow  a user to alter the environment
prior to the execution of a program but for C the biggest problem
occurs when a program calls out of its current encapsulation into
another  program.  Due to  C requiring that  inter-execution unit
calls have an initialized environment  a new mechanism similar to
run  unitis will  be developed.    This new  mechanism will  be a
combination of an entrypoint `main_' and a new link type.

With  this in  mind we  will now  discuss the  solution which  is
proposed  for  C  on  Multics.   This  solution  is  made up of a
coordinated use of a new  Link Editor, the entrypoint 'main_' and
the new link type.


MTB-691                                Multics Technical Bulletin
                                        Multics C Exe. Env. Spec.

5.  Link Editor

A  new  tool  will  be  introduced  to  handle  the resolution of
external  references and the  initialization of C's  external and
static  variables.  This  tool will  be called  the Multics  Link
Editor and will be fully defined in a later MTB.

The  entire  purpose  of  the  Link  Editor  is to facilitate the
porting of third  party software to Multics from  systems that do
not support dynamic linking and single process environments.

5.1.  Similarities With The Binder

The function  of the Link Editor  will be similar to  the current
Multics Binder in that it will join together a series of compiled
segments.  It  will resolve all  external references that  can be
found within the supplied  segments.  Any references not resolved
by the combining  of the object segments will be  left as Multics
external references, and will be dynamically linked at runtime.

The  Link   Editor  will  also  combine   initialization  of  all
externally defined  and static variables  into a single  block or
group definition.  This will be  contained at the global level of
the execution unit, as is currently done with the Multics Binder.

5.2.  Extensions From The Binder

There are  a series of extensions  that the new Link  Editor will
have over the current Binder.  These extensions can be defined as
follows:

1)   The   Link   Editor   will    allow   specification   of   a
     library/directory  in  which   external  references  may  be
     resolved.  If the external reference can not be resolved, it
     is left as an external reference.
2)   The Link  Editor will have  a different user  interface than
     the current  Binder.  The Link  Editor will allow  a user to
     define a link request on a single command line and will also
     understand a more precise link definition request which will
     be  contained in  an archive  or directory  (as is currently
     done with the Binder).


Multics Technical Bulletin                                MTB-691
Multics C Exe. Env. Spec.

3)   In the future, the Link Editor may produce what we will call
     a `Very Large Object' that will execute on Multics.
4)   The Link Editor will produce relocatable output.
5)   The Link Editor should be easy to use, and should have a set
     of  defined defaults that  may be replaced  by the users  as
     they see fit.

6.  `Main_'

To allow Multics to find  an entrypoint within an executable unit
an  entrypoint  named  `main_'  will  be  linked  by the normal C
command  or by  the user.   If  `main_'  is not  linked with  the
executable unit,  Multics will enter the executable  unit via the
entrypoint "segname$segname".

The entrypoint `main_' will be responsible for the control of the
per-execution-process environment.   This entrypoint will  have a
specific set of functions which can be defined as follows:

1)   Set up cleanup handlers and abort condition handlers.
2)   Initialize the heap area and stack execution environment.    |
3)   Convert  the output  of the  Multics command  processor into
     Argc and Argv.
4)   Initialize the C standard I/O  descriptors 0,1,2 and the I/O
     descriptor block.  This is defined in MTB 689.
5)   Call the main entrypoint within the execution unit.
6)   Cleanup malloced space and close files.
7)   Reset the Execution Environment.                             |

The following sections outline each function in more detail:

6.1.  Cleanup and Abort Handlers

In  order for the  per-execution-process environment to  be reset
after an  abort has taken  place, a series  of condition handlers
have to be set up in 'main_'.  These condition handlers will take
care of freeing allocated space and closing opened files, or they
will  handle the returning  of an execution  unit to the  command
level after a break has taken place.


MTB-691                                Multics Technical Bulletin
                                        Multics C Exe. Env. Spec.

6.2.  Heap and Execution Environment Initialization

To  allow for the  creation of C  default structures such  as the
iocb block (defined  in MTB 689) the heap will  be initialized in
'main_'.   This  will  also  allow  for  future  improvements  in
allocation  if  a  user  can  specify  how  much  space  is to be
initialized at the begining of the execution unit.

If the program is being entered recursively the LOT and ISOT will |
have to be  saved and reinitialized so that  links snapped within |
this execution unit are resolved to new copies of the objects.    |

6.3.  Convert Argc and Argv

The conversion  of the input  line from the  command processor to
the  Argc, Argv format  will be done  in 'main_'.  Argc  and Argv
will  be allocated  in the   heap in  contiguous space.   Argv[0]
points at  the invocation name of the  execution unit.  Currently
the  Multics command  processor  does  not have  this information
available.  Changes will be made to cu_ and the command processor
that  will allow the  command name to  be retreived.  For  a more
detailed description see the Mtb entitled "Changes to the Command
Processor  Required by  C".  This  implies that  calls to  C main
routines should be  done only via the C system  call or by cu_$cp
elsewhere.

6.4.  Initialize I/O Structures

The iocb  block will be allocated  in the heap to  allow it to be
reallocated by the user.  Included  in this is the initialization
of indexes  0, 1 and 2  to be the IOCB  pointers to stdin, stdout
and stderr.

6.5.  Call main

The entrypoint main in the execution unit will be called with the
parameters Argc and Argv.

6.6.  Cleanup of Space and Files

'Main_'  will set  up a  method for  freeing allocated  space and
resetting the  per-execution-process environment upon  exit under
normal circumstances.


Multics Technical Bulletin                                MTB-691
Multics C Exe. Env. Spec.

6.7.  Reset Execution Environment

If the routine was entered recursively the LOT and ISOT will have |
to  be  reset  to  the  previous  values  to  reset  the external |
references.                                                       |

With this entrypoint included in  an execution unit, the problems
of  operating  under  a  per-login-process  environment  will  be
resolved.   This entrypoint will  ensure that the  environment is
reset each time it is exited or entered.

The implementation of the proposed solution will be done over two
versions  of the  compiler; the  Demo version  and the Production
version.   In the Demo  version of the  compiler `main_' will  be
implemented.  This along with the current binder will allow for C
programs  to execute in  the standard Multics  environment.  This
implies that C external and  static variables will be implemented
as *system  links.  With C external and  static variables defined
as *system links the following limitations will be placed on C in
the Demo version of the compiler:

1) A method  is required to  specify link initialization  to alm.
   This will be defined in another MTB entitled Required C Pseudo
   Ops for Alm.
2) Execution units  will have to be self  contained; no guarantee
   will  be  given  that   initialization  will  be  done  across
   execution units.
3) The  user must  ensure that  the C  library is  second in  the
   standard search rules after their current working directory.

The Production  version of the  compiler will include  the use of
the Link Editor to resolve library conflicts and external storage
definitions.   `main_' will  be responsible  for initializing the
LOT and ISOT  tables if it was called recursively.   It will save
the  current values  of the  LOT and  ISOT and  will then set the
entries to lot_fault.  With this in place when a C execution unit
is  called  recursively  the  lot_fault  will  force the combined
linkage section to be copied out reseting all external references
including  *system links.   `main_' will  reset the  LOT and ISOT
entries on exit resetting the environment.

Again,  the  proposed  solution  for  C  is  a coordinated use of
`main_'  and  the  new  Multics  Link  Editor.   At this point no
attempt  will be made  to propose a  solution for tasking,  as we
feel that tasking is a function of the operating system and not a
function of the C language.