10/31/90  HH07 (Multics C User's Guide)
          Errata Information for MR12.4


pg 2-4:  replace the section "Size of Data Types" with the        |
     following in order to include the examples.                  |
                                                                  |
     _S_i_z_e _o_f _D_a_t_a _T_y_p_e_s                                           |
                                                                  |
     A program may need to know the size of a particular data     |
     type.  If this is hardcoded into the program, the code will  |
     not be portable if the data type sizes between the two       |
     machines differ.  For example, a program may use the maximum |
     size of an int in an expression as follows:                  |


         #define MAXINT 32767 /* largest int on a machine with    |
                                 a 16 bit int */                  |
            .                                                     |
            .                                                     |
            .                                                     |
         if (y == MACINT) .......                                 |
                                                                  |
     This code could cause incorrect results on Multics.  Multics |
     has a 36-bit integer so the value of MAXINT is not the       |
     maximum integer size on the Multics hardware.  The following |
     code would correct the situation:                            |
                                                                  |
         #define MAXINT ((int) (((unsigned ) - 1) >> 1))          |


     The following examples illustrate nonportable and portable   |
     ways of coding word definitions.                             |
                                                                  |
     Nonportable Example:                                         |
                                                                  |
         #define word 4 /* hardcoded number of bytes in an        |
                           integer */                             |
                                                                  |
     Portable Example:                                            |
                                                                  |
         #define word sizeof(int)                                 |


pg 2-6:  replace the page with the following in order to include  |
     the examples.                                                |
                                                                  |
     To fix the problem, the Multics C programmer must define     |
     these functions as returning a long or a pointer.  While     |
     returning a pointer in a long is allowed, it is not          |
     recommended.                                                 |
                                                                  |
     The following code samples illustrate nonportable and        |
     portable cases of returning a pointer as an integer.         |


     Nonportable Example:                                         |


         my_func()       /* function returns an int as default */ |
         {                                                        |
         int *p;         /* a pointer to an int */                |
                                                                  |
         if (some_test) return (p);                               |
                         /* returns a pointer in an integer */    |
                                                                  |
         }                                                        |


     Portable Example:                                            |
                                                                  |
         int *my_func()  /* function returns pointer to an int */ |
         {                                                        |
         int *p;         /* a pointer to an int */                |
                                                                  |
         return (p);     /* returns a pointer in a pointer        |
                            location */                           |
         }                                                        |
                                                                  |
     The following example shows a nonportable case of an integer |
     holding a pointer, followed by a portable fix for Multics:   |


     Nonportable Example:                                         |
                                                                  |
         int i;                                                   |
         struct {                                                 |
                    char y[10];                                   |
                    int p;                                        |
                    } qbert, *t;                                  |
         t = &qbert;               /* t points to structure */    |
         i = t;                    /* assign pointer to integer */|
         i += 5;                   /* point to y[5] */            |


     Portable Example:                                            |
                                                                  |
         char *p;                                                 |
                                                                  |
         p = &qbert.y[0];          /* point to start of y */      |
         p += 5;                   /* point to y[5] */            |
                                                                  |
     Be careful when you use pointers.  Pointers on a VAX         |
     implementation are automatically initialized to zero when    |
     the stack frame is first allocated.  Since zero is also the  |
     NULL value, the pointers can be used with no                 |
     pre-initialization.                                          |


pg 2-7:  replace the first part of the page with the following in |
     order to include the examples.                               |
                                                                  |
     On Multics, you get no automatic initialization, therefore,  |
     a pointer must be initialized explicitly to NULL before it   |
     is used.  The following examples illustrate nonportable and  |
     portable cases of this.                                      |


     Nonportable Example:                                         |
                                                                  |
         int *y[10];                                              |
         if (y[3] == NULL).........;                              |
             /* no guarantee that y[3] has been assigned          |
                to NULL */                                        |
                                                                  |
     Portable Example:                                            |
                                                                  |
         int *y[10] = { NULL, NULL, ....};                        |
             /* explicitly initialize array of pointer to NULL */ |


     _T_h_e _N_u_l_l _P_o_i_n_t_e_r _V_a_l_u_e                                       |
                                                                  |
     In most implementations the null pointer value NULL is       |
     defined to be the int value 0.  It is not uncommon to see    |
     NULL used as a substitute for 0.  On Multics the pointer     |
     value NULL is not 0, but -1|1.                               |
                                                                  |
     The following two examples show implementations in which     |
     NULL is 0, which could cause portability problems:           |


     Example 1                                                    |
                                                                  |
         int p;                                                   |
                                                                  |
         if (p == NULL)......                                     |
               /* use Null as substitute for zero */              |
                                                                  |
     Example 2                                                    |
                                                                  |
         int *t[10];                                              |
                                                                  |
         t[NULL] = 0;                                             |
               /* NULL used as subscript zero */                  |


pg 3-2 to 3-3:  replace the documentation for "c_compile" with
     the following.

     cc

     SYNTAX:  cc pathnames {-control_args}

     FUNCTION:  cc is used to process and link-edit C programs.
     cc will process input files and generate a single
     link-edited object.  When invoked with multiple pathnames,
     cc will also leave unlinked object segments (with a '.cob'
     suffix) for each file assembled.  cc will invoke the C
     preprocessor, the C Compiler, the assembler, and the Linkage
     Editor as appropriate for each input file.


     ARGUMENTS:
     pathnames
        are pathnames of files that are to be processed; the
        amount of processing is determined by the pathname's
        suffix (such as '.c', '.cpp', '.cob', or '.alm') .
        cc processes files in phases by invoking the C 
        preprocessor, then the C Compiler, then the assembler, 
        and then finally the Linkage Editor.  Pathnames that have
        the '.c' suffix are processed by all phases.  Pathnames 
        that have the '.cpp' suffix start with the C Compiler
        phase. Pathnames that have the '.alm' suffix start with
        the assembly phase.  All other pathnames are processed by
        only the final Linkage Editor phase.


     CONTROL ARGUMENTS:
     -brief, -bf
        Suppress printing of messages that state the current pass
        being performed.  (Default)

     -definition args, -def args
        Specifies define names to be defined or undefined in the
        preprocessor, where "args" is a list of define names
        separated by commas with no spaces (in the following
        form):

           -def n,x=2,^y


        The first arg specifies that n is to be defined as 1 in
        the same way as '#define n' would define n to be 1.  The
        second arg specifies that x is to be given a definition
        of 2 and the last arg specifies that y is to be undefined
        in the preprocessor.  A maximum of ten defines and ten
        undefines are allowed.

     -include paths, -incl paths
        Specifies the pathnames of include file directories the
        user wishes the preprocessor to look in for include
        files.  All arguments up to the next control argument are
        treated as include directory pathnames.  A maximum of ten
        include directories can be specified.


     -library paths, -lb paths
        Specifies the pathnames of library directories, archives
        or object files the user wishes the Linkage Editor to use
        when resolving external references.  All arguments up to
        the next control argument are treated as include library
        pathnames.  A maximum of ten libraries can be specified.

     -list, -ls
        Specifies that a Linkage Editor listing file should be
        generated for the Linkage Editor pass of c_compile.  The
        listing file will specify where the objects brought in by
        the Linkage Editor were found.


     -long, -lg
        Specifies that a message should be printed specifying the
        completion of each pass of the compiler for each
        specified pathname.

     -output_file pathname, -of pathname
        Forces the output to be placed in the file defined by
        pathname.  If no output file name is given the output
        will be put into the Linkage Editor's default output file
        'a.out'.


     -stop_after pass, -spaf pass
        Tells cc to stop after the specified pass of the
        compiler.  Valid values for pass are:

        preprocessor, pp:  generates a ".cpp" file which is the
             output from the preprocessor.

        c: generates a ".alm" file which is an alm source file
             which is the output from the C compiler.

        alm: generates a ".cob" file which is the intermediate
             executable file which is the output from the
             assembler.  This file is normally used as the input
             to the Linkage Editor.


     -table, -tb
        Generates a full symbol table for use by symbolic
        debuggers.  The symbol table is part of the symbol
        section of the object program and consists of two parts:
        a statement map that gives the correspondence between
        source line numbers and object locations of the source,
        and an identifier table containing information about
        every identifier referenced in the source program.

     NOTES:
     C_compile has been altered to use the standard search rules
     to find the default C runtime library (runtime.archive).
     This library is normally located in >sl3p>cc>e and will be
     found automatically by the referencing_dir search rule.


pg 4-59:  for the "execve" routine, add the following description
     to the RETURN VALUE section.

     The return value will take on the following format.  If an
     error occurs during the creation of the child, errno will be
     set to indicate the error and the return value will be
     negative.  Otherwise, the return value will give information
     about the termination of the child process as follows:


     RETURN VALUE <= EXIT STATUS|CORE BIT|SIGNAL NUMBER


     EXIT STATUS is an 8 bit value (sign extended to fill out the
     rest of the word) specified as an argument to the exit
     function.

     CORE BIT is a single bit value that indicates that a core
     dump has been generated (this value will always be zero on
     Multics).

     SIGNAL NUMBER is a 7 bit value representing the signal
     number that may have caused the child's termination (Example
     SIGFPE = 8).

     Note:  because of sign extension, a negative EXIT STATUS
     will result in a negative return value.


pg 4-158:  insert the following documentation for the "putenv"    |
     routine between the "putchar" routine (pg 4-158) and the     |
     "puts" routine (pg 4-159).                                   |
                                                                  |
     _p_u_t_e_n_v                                                       |
                                                                  |
         Changes or adds value to environment.                    |
                                                                  |
         SYNTAX:                                                  |
                                                                  |
             int putenv (string)                                  |
             char *string;                                        |


         ARGUMENTS:                                               |
                                                                  |
         string                                                   |
             Points to a string of the form "name=value".         |
                                                                  |
                                                                  |
         DESCRIPTION:                                             |
                                                                  |
         Putenv makes the value of the environment variable name  |
         equal to value by altering an existing variable or       |
         creating a new one.  In either case, the string pointed  |
         to by string becomes part of the environment, so         |
         altering the string will change the environment.  The    |
         space used by string is no longer used once a new        |
         string-defining name is passed to putenv.                |


         DIAGNOSTICS:                                             |
                                                                  |
         Putenv returns non-zero if it was unable to obtain       |
         enough space via malloc for an expanded environment;     |
         otherwise, it returns zero.                              |


         RELATED FUNCTIONS:                                       |
                                                                  |
         exec, getenv, malloc, environ                            |


         WARNINGS:                                                |
                                                                  |
         Putenv manipulates the environment pointed to by         |
         environ, and can be used in conjunction with getenv.     |
         However, envp (the third argument to main) is not        |
         changed.  This routine uses malloc to enlarge the        |
         environment.  After putenv is called, environmental      |
         variables are not in alphabetical order.  A potential    |
         error is to call putenv with an automatic variable as    |
         the argument, then exit the calling function while       |
         string is still part of the environment.                 |


pg 4-196:  for the "system" routine, add a new section (RETURN
     VALUE) with the information below.

     RETURN VALUE:

     The return value will take on the following format.  If an
     error occurs during the creation of the child, errno will be
     set to indicate the error and the return value will be
     negative.  Otherwise, the return value will give information
     about the termination of the child process as follows:

     RETURN VALUE <= EXIT STATUS|CORE BIT|SIGNAL NUMBER


     EXIT STATUS is an 8 bit value (sign extended to fill out the
     rest of the word) specified as an argument to the exit
     function.

     CORE BIT is a single bit value that indicates that a core
     dump has been generated (this value will always be zero on
     Multics).

     SIGNAL NUMBER is a 7 bit value representing the signal
     number that may have caused the child's termination (Example
     SIGFPE = 8).

     Note:  because of sign extension, a negative EXIT STATUS
     will result in a negative return value.
