MULTICS TECHNICAL BULLETIN                             MTB-762-01

To:       MTB Distribution

From:     Douglas G. Howe

Date:     March 30, 1987

Subject:  C Runtime Extensions


This MTB gives the descriptions of the runtime extension routines
that  are being  ported from  UNIX  System  V to  run on  Multics
version 12.0.

Revision 1 contains added information on GETGID and LOGNAME.      |

Note that the descriptions of these routines have been taken from
the "UNIX System V - Release 2.0 Programmer Reference Manual, DEC
Processors", Sections 2 and 3.


Comments on this MTB should be sent to the author -

     via Multics mail to:


     via telephone to:

        Douglas G.  Howe, ACTC (403) 284-6432

     via forum on System-M to:

        >udd>Multics>DGHowe>meetings>c_imp (c)


(1) UNIX is a trademark of AT&T Bell Laboratories.

(2) DEC is a trademark of Digital Equipment Corporation.

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

C Runtime Extensions                                   MTB-762-01

                        TABLE OF CONTENTS

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

1          1     ABORT
2          2     ACCESS
3          3     ALARM
4          4     CB
5          5     CLOCK
6          6     CTIME
7          7     ENVIRON
7.1        8     . . GETENV
7.2        9     . . PUTENV
8          10    EXEC
9          12    FCNTL
10         13    GETCWD
11         14    GETGID
12         15    GETLOGIN
13         16    GETOPT
14         17    GETPID
15         18    GETUID
16         19    IOCTL
17         21    LINK
18         22    LOGNAME
19         23    PERROR
20         24    RAND
21         25    SLEEP
22         26    STAT
23         28    STRING
24         29    STRTOD
25         30    STRTOL
26         31    SWAB
27         32    TIMES
28         33    VARARGS
29         34    VPRINTF

C Runtime Extensions                                   MTB-762-01


NAME:  abort - generate an IOT fault


   int abort ( )


   abort first closes all open  files if possible, then causes an
   IOT signal to be sent to the process.  This usually results in

   It is possible for abort to return control if SIGIOT is caught
   or ignored,  in which case the  value returned is that  of the
   kill system call.


(1) Taken from UNIX System V - Release 2.0 - Programmer Reference
    Manual, sections 2 and 3.

MTB-762-01                                   C Runtime Extensions


NAME:  access - determine accessibility of a file


   int acess (path, amode)
   char *path;
   int amode;


   Path points to  a path name naming a file.   Access checks the
   named  file for  accessibility  according  to the  bit pattern
   contained  in amode.   The bit  pattern contained  in amode is
   constructed as follows:

       04          read
       02          write
       01          excute (search)
       00          check existence of file

C Runtime Extensions                                   MTB-762-01


NAME:  alarm - set a process alarm clock


   unsigned alarm (sec)
   unsigned sec;


   Alarm  instructs the  alarm clock  of the  calling process  to
   signal SIGALRM after the number of real time seconds specified
   by sec have elapsed; see signal.

   Alarm  requests are  not stacked;  successive calls  reset the
   alarm clock of the calling process.

   If sec is 0, any previously made alarm request is canceled.

MTB-762-01                                   C Runtime Extensions

4.  CB

NAME:  cb - program beautifier


   cb [ -s ] [ -j ] [ -1 leng ] [ file .  .  .]


   Cb  reads C  programs either  from its  arguments or  from the
   standard  input and  writes them  on the  standard output with
   spacing  and indentation  that displays  the structure  of the
   code.  Under default options,  cb preserves all user newlines.
   Under the  -s flag cb canonicalizes  the code to the  style of
   Kernighan and  Ritchie in The C Programming  Language.  The -j
   flag causes split lines to be  put back together.  The -1 flag
   causes cb to split lines that are no longer than leng.

C Runtime Extensions                                   MTB-762-01


NAME:  clock - report CPU time used


   long clock ( )


   Clock returns  the amount of  CPU time (in  microseconds) used
   since the first call to clock.

MTB-762-01                                   C Runtime Extensions


NAME:   ctime, localtime, gmtime,  asctime, tzset -  convert date
and time to string

   #include <time.h>

   char *time (clock)
   long *clock;

   struct tm *localtime (clock)
   long *clock;

   struct tm *gmtime (clock)
   long *clock;

   char *asctime (tm)
   struct tm *tm;

   extern long timezone;

   extern int daylight;

   extern char *tzname[2];

   void tzset (  )


   Ctime   converts  a  long   integer,  pointed  to   by  clock,
   representing the  time in seconds since  00:00:00 GMT, January
   1, 1970, and returns a pointer to a 26-character string in the
   following form.  All the fields have constant width.

                     Sun Sep 16 01:03:52 1873n0

   Localtime  and  gmtime  return  pointers  to  "tm" structures,
   described  below.  Localtime  corrects for  the time  zone and
   possible  Daylight Savings  Time; gmtime  coverts directly  to
   Greenwich Mean Time  (GMT), which is the time  the UNIX system

   Asctime converts a "tm" structure to a 26-character string, as
   shown  in the  above example,   and returns  a pointer  to the

C Runtime Extensions                                   MTB-762-01


NAME:  environ - user environment


   An array of strings called the "environment" is made available
   by exec  when a process begins.  By  convention, these strings
   have the  form "name=value".  The following names  are used by
   various commands:

   HOME   Name of the user's login directory, set by login

   TERM   The kind of terminal for which output is to be prepared.


   Time zone information.  The format is xxxnzzz where xxx is
   standard local time zone abbreviation, n is the difference in hours
   from GMT, and zzz is the abbreviation for the daylight-saving local
   time zone, if any; for example, EST5EDT.

MTB-762-01                                   C Runtime Extensions

7.1.  GETENV

NAME:  getenv - return value for environment name


   char *getenv (name)
   char *name


   Getenv  searches  the  environment  list  (see  environ) for a
   string of the form name =  value, and returns a pointer to the
   value in the current environment  if such a string is present,
   otherwise a NULL pointer.

C Runtime Extensions                                   MTB-762-01

7.2.  PUTENV

NAME:  putenv - change or add value to environment


   int putenv (string)
   char *string;


   String points  to a string  of the form  "name=value."  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.

MTB-762-01                                   C Runtime Extensions

8.  EXEC

NAME:  execl,  execv, execle, execve, execlp, execvp  - execute a


   int execl (path, arg0, arg1, ..., argn, 0)
   char *path, arg0, *arg1, ..., *argn;

   int execv (path, argv)
   char *path, *argv[ ];

   int execl (path, arg0, arg1, ..., argn, 0, envp)
   char *path, *arg0, *arg1, ..., *argn, *envp[ ];

   int execve (path, argv, envp)
   char *path, *argv[ ], *envp[ ];

   int execlp (file, arg0, arg1, ..., argn, 0)
   char  *file, *arg0, *arg1, ..., *argn;

   int execvp (file, argv)
   char *file, *argv[ ];


   Exec in all  its forms transfers control to  the specified new

   When a C program is executed, it is called as follows:

       main (argc, argv, envp)
       int argc;
       char **argv, **envp;

   where  argc is  the argument  count and  argv is  an array  of
   character pointers to the arguments themselves.  As indicated,
   argc is  conventionally at least  one and the  first member of
   the array points to a string containing the name of the file.

   Path  points to a  path name that  identifies the new  process

   File points to the new process file.

   Arg0,  argl,   ...,  argn  are  pointers   to  null-terminated
   character strings.  These strings constitute the argument list
   available to  the new process.   By convention, at  least arg0
   must be present and point to a string that is the same as path
   (or its last component).

C Runtime Extensions                                   MTB-762-01

   Argv  is an  array  of  character pointers  to null-terminated
   strings.  These strings constitute the argument list available
   to the  new process.  By  convention, argv must  have at least
   one member, and it must point to  a string that is the same at
   path (or  its last component).   Argv is terminated  by a null

   Envp  is an  array  of  character pointers  to null-terminated
   strings.  These strings constitute the environment for the new
   process.  Envp is terminated by a null pointer.  For execl and
   execv, the  C run-time start-off  routine places a  pointer to
   the environment of the calling process in the global cell:

       extern char **environ;

   and it is used to pass  the environment of the calling process
   to the new process.

MTB-762-01                                   C Runtime Extensions


NAME:  fcntl - file control


#include <fcntl.h>

int fcntl (fildes, cmd, arg)
int fildes, cmd, arg;


   Fcntl provides for control over open files.  Fildes is an open
   file descriptor  obtained from a  creat, open or  fcntl system

   The commands available are:


   Get file status flags.


   set file status flags to arg.   Only certain flags can be set;
   see fcntl.

C Runtime Extensions                                   MTB-762-01


NAME:  getcwd - get path-name of current working directory


   char *getcwd (buf, size)
   char *buf;
   int size;


   Getcwd returns  a pointer to the  current directory path-name.
   The value of size must be at least two greater than the length
   of the path-name to be returned.

   If  buf is a  NULL pointer, getcwd  will obtain size  bytes of
   space  using malloc.   In this  case, the  pointer returned by
   getcwd  may be used  as the argument  in a subsequent  call to

MTB-762-01                                   C Runtime Extensions

11.  GETGID                                                       |
NAME:  getgid - get real group IDs.                               |
SYNOPSIS                                                          |
   unsigned short getgid ()                                       |
DESCRIPTION                                                       |
   Getgid returns the real group ID of the calling process.       |

C Runtime Extensions                                   MTB-762-01


NAME:  getlogin - get login name


   char *getlogin ( );


   Getlogin returns a pointer to the login name.

MTB-762-01                                   C Runtime Extensions


NAME:  getopt - get option letter from argument vector


   int getopt (argc, argv, optstring)
   int argc;
   char **argv, *opstring;

   extern char *optarg;
   extern int optind, opterr;


   Getopt returns the  next option letter in argv  that matches a
   letter  in optstring.   Optstring  is  a string  of recognized
   option letters; if a letter is followed by a colon, the option
   is  expected  to  have  an  argument  that  may  or may not be
   separated from it  by white space.  Optarg is set  to point to
   the start of the option argument on return from getopt.

   Getopt places in optind the argv index of the next argument to
   be  processed.   Because  optind  is  external  it is normally
   initialized  to zero  automatically before  the first  call to

   When all  options have been  processed (i.e., up  to the first
   non-option argument), getopt returns  EOF.  The special option
   - - may be used to delimit the end of the options; EOF will be
   returned, and - - will be skipped.

C Runtime Extensions                                   MTB-762-01


NAME:  getpid - get process ID.


   int getpid ()


   Getpid returns the process ID of the calling process.

MTB-762-01                                   C Runtime Extensions


NAME:  getuid - get user ID.


   unsigned short getuid ()


   Getuid returns the user ID of the calling process.

C Runtime Extensions                                   MTB-762-01

16.  IOCTL

NAME:  ioctl - control device


   ioctl (fildes, request, arg)
   int fildes, request;


   Ioctl  performs a  variety of  functions on  character special
   files (devices).

   Several  ioctl  system  calls  apply  to  terminal files.  The
   primary  calls   use  the  following  structure,   defined  in

       #define   NCC    8
       struct    termio {
       unsigned    short     c_iflag;     /* input modes */
       unsigned    short     c_oflag;     /* output modes */
       unsigned    short     c_cflag;     /* control modes */
       unsigned    short     c_lflag;     /* local modes */
       char                  c_line;      /* line discipline */
       unsigned    char      c_cc[NCC];   /* control chars */

    The primary ioctl system calls have the form:

       ioctl  (fildes, command, arg)
       struct termio *arg;

    The commands using this form are:


       Get the parameters associated  with the terminal and store
       in the termio structure referenced by arg.


       Set the  parameters associated with the  terminal from the
       structure referenced by arg.  The change is immediate.


       Wait  for  the  output  to  drain  before  setting the new
       parameters.   This  form  should  be  used  when  changing
       parameters that will affect output.

MTB-762-01                                   C Runtime Extensions


       Wait for the  output to drain, then flush  the input queue
       and set the new parameters.

    Additional ioctl(2) calls have the form:

       ioctl (fildes, command, arg) int arg;

    The commands using this form are:


       Wait for  the output to drain.   If arg is 0,  then send a


       Start/stop control.   If arg is  0, suspend output;  if 1,
       restart suspended output.


       If arg is 0, flush the input queue; if 1, flush the output
       queue; if 2, flush both the input and output queues.

C Runtime Extensions                                   MTB-762-01

17.  LINK

NAME:  link - link to a file


   int link  (path, *path2;
   char *path1, *path2;


   Path1 points  to a path  name naming an  existing file.  Path2
   points  to a path  name naming the  new directory entry  to be
   created.  Link creates a new link for the existing file.

MTB-762-01                                   C Runtime Extensions

18.  LOGNAME                                                      |
NAME:  logname - return login name of user                        |
SYNOPSIS                                                          |
   char *logname()                                                |
DESCRIPTION                                                       |
   Logname returns  a pointer to the  null-terminated login name; |
   it extracts the $LOGNAME variable from the user's environment. |

C Runtime Extensions                                   MTB-762-01


NAME:   perror,  errno,  sys_errlist,  sys_nerr  -  system  error


   void perror (s)
   char  *s;

   extern int errno;

   extern  char  *sys_errlist[ ];

   extern  int  sys_nerr;


   Perror  produces  a  message  on  the  standard  error output,
   describing  the last  error encountered   during a  call to  a
   system or library function.  The  argument string s is printed
   first, then  the message and a  new-line.  To be of  most use,
   the  argument string  should include  the name  of the program
   that incurred the  error.  The error number is  taken from the
   external variable  errno, which is  set when errors  occur but
   not cleared when non-erroneous calls are made.

   To  simplify  variant  formatting  of  messages,  the array of
   message strings sys_errlist is provided;  errno can be used as
   an index in  this table to get the message  string without the
   new-line.  Sys_nerr is the largest  number provided for in the
   table;  it should be  checked because new  error codes may  be
   added to the system before they are added to the table.

MTB-762-01                                   C Runtime Extensions

20.  RAND

NAME:  rand, srand - simple random-number generator


   int  rand  ( )

   void  srand  (seed)
   unsigned seed;


   Rand   uses   a   multiplicative   congruential  randon-number
   generator  with  period  2(the   power  of  32)  that  returns
   successive pseudo-random numbers in the range from 0 to 2( the
   power of 15)-1.

   Srand  can be called  at any time  to reset the  random-number
   generator  to  a  random  starting  point.   The  generator is
   initially seeded with a value of 1.

C Runtime Extensions                                   MTB-762-01

21.  SLEEP

NAME:  sleep - suspend execution for interval


   unsigned sleep (seconds)
   unsigned seconds;


   The current process is suspended from execution for the number
   of seconds specified by the argument.

MTB-762-01                                   C Runtime Extensions

22.  STAT

NAME:  stat, fstat - get file status


   #include <sys/types.h>
   #include <sys/stat.h>

   int  stat  (path, buf)
   char  *path;
   struct  stat  *buf;

   int fstat  (fildes,  buf)
   int fildes;
   struct  stat  *buf;


   Path  points to a  path name naming  a file.  Read,  write, or
   execute permission of the named  file is not required, but all
   directories listed in  the path name leading to  the file must
   be searchable.  Stat obtains information about the named file.

   Similarly, fstat obtains information  about an open file known
   by  the file  descriptor  fildes,  obtained from  a successful
   open, creat or fcntl system call.

   Buf is a pointer to a stat structure into which information is
   placed concerning the file.

   The contents  of the structure  pointed to by  buf include the
   following members:

       ushort  st_mode;  /* File mode; see mknod(2) */
       ino_t   st_ino;   /* Inode number */
       dev_t   st_dev;   / * ID of device containing */
                         /* a directory entry for this file */
       dev_t   st_rdev;  /* ID of device */
                         /* This entry is defined only for */
                         /* character special or block special files */
       short   st_nlink; /* Number of links */
       ushort  st_uid;   /* User ID of the file's owner */
       ushort  st_gid;   /* Group ID of the file's group */
       off_t   st_size;  /* File size in bytes */
       time_t   st_atime; /* Time of last access */
       time_t   st_mtime; /* Time of last data modification */
       time_t  st_ctime;  /* Time of last file status change */
                          /* Times measured in seconds since */
                          /* 00:00:00 GMT, Jan. 1, 1970 */

C Runtime Extensions                                   MTB-762-01

       st_time     Time when file date was last changed.

       st_mtime    Time when data was last modified.

       st_ctime    Time when file status was last changed.

MTB-762-01                                   C Runtime Extensions


NAME:  strpbrk, strspn, strcspn, strtok, - string operations


   #include <string.h>

   char *strpbrk (s1, s2)
   char *s1, *s2;

   int strspn  (s1, s2)
   char *s1, *s2;

   int strcspn  (s1, s2)
   char *s1, *s2;

   char *strtok  (s1, s2)
   char *s1, *s2;


   The  arguments  s1,  s2  and  s  point  to  strings (arrays of
   characters teminated by a null character).

   Strpbrk returns a pointer to the first occurrence in string s1
   of  any character  from string  s2, or  a NULL  pointer if  no
   character from s2 exists in s1.

   Strspn (strcspn) returns the length  of the initial segment of
   string  s1 which  consists  entirely  of characters  from (not
   from) string s2.

   Strtok  considers the string  s1 to consist  of a sequence  of
   zero  or more text  tokens separated by  spans of one  or more
   characters from the separator string s2.  The first call (with
   pointer s1 specified) returns a pointer to the first character
   of  the first token,  and will have  written a null  character
   into  s1  immediately  following   the  returned  token.   The
   function  keeps track  of its  position in  the string between
   separate calls,  so that subsequent calls (which  must be made
   with the first argument a  NULL pointer) will work through the
   string  s1  immediately  following  that  token.   In this way
   subsequent  calls will  work through  the string  s1 until  no
   tokens remain.  The separator string  s2 may be different from
   call to call.  When no token  remains in s1, a NULL pointer is

C Runtime Extensions                                   MTB-762-01


NAME:  strtod - convert string to double-precision number


   double strtod  (str, ptr)
   char  *str,  **ptr;


   Strtod returns as a double-precision floating-point number the
   value represented  by the character string pointed  to by str.
   The string is scanned up to the first unrecognized character.

MTB-762-01                                   C Runtime Extensions


NAME:  strtol, atol, atoi - convert string to interger


   long strtol  (str, ptr, base)
   char  *str  **ptr;
   int base;


   Strtol returns as a long  integer the value represented by the
   character string pointed to by  str.  The string is scanned up
   to  the first character  inconsistent with the  base.  Leading
   "white-space" characters are ignored.

C Runtime Extensions                                   MTB-762-01

26.  SWAB

NAME:  swab - swab bytes


   void swab  (from, to, nbytes)
   char *from, *to;
   int nbytes;


   Swab  copies nbytes  bytes pointed   to by  from to  the array
   pointed  to by  to, exchanging  adjacent even  and odd  bytes.
   Nbytes should be even and  non-negative.  If nbytes is odd and
   positive swab  uses nbytes-1 instead.  If  nbytes is negative,
   swab does nothing.

MTB-762-01                                   C Runtime Extensions

27.  TIMES

NAME:  times - get process and child process times


   #include <sys/types.h>
   #include <sys/times.h>

   long times (buffer)
   struct tms *buffer;


   Times   fills  the  structure   pointed  to  by   buffer  with
   time-accounting information.   The following are  the contents
   of this structure:

   struct  tms {
               time_t  tms_utime;
               time_t  tms_stime;
               time_t  tms_cutime;
               time_t  tms_cstime;

   This information  comes from the  calling process and  each of
   its  terminated child  processes for  which it  has executed a
   wait.  All times are in 100ths of a second.

   Tms_utime is the CPU time used while executing instructions in
   the user space of the calling process.

   Tms_stime is the CPU time used  by the system on behalf of the
   calling process.  Will be zero.

   Tms_cutime is the sum of the tms_utimes and tms_cutimes of the
   child processes.  Will be zero.

   Tms_cstime is the sum of the tms_stimes and tms_cstimes of the
   child processes.  Will be zero.

C Runtime Extensions                                   MTB-762-01


NAME:  varargs - handle variable argument list


   #include <varargs.h>



   void va_start(pvar)
   va_list pvar;

   type va_arg(pvar, type)
   va_list pvar;

   void va_end(pvar)
   va list pvar;


   This  set of  macros  allows  portable procedures  that accept
   variable  argument lists  to be  written.  Routines  that have
   variable  argument  lists  (such  as  printf)  but  do not use
   varargs are inherently nonportable,  as different machines use
   different argument-passing conventions.

   va_alist is used as the parameter list in a function header.

   va_dcl  is a  declaration for  va_alist.  No  semicolon should
   follow va_dcl.

   va_list is  a type defined  for the variable  used to traverse
   the list.

   va_start is called to initialize  pvar to the beginning of the

   va_arg will return the next argument in the list pointed to by
   pvar.   Type  is  the  type  the  argument  is expected to be.
   Different types can  be mixed, but it is up  to the routine to
   know  what  type  of  argument  is  expected,  as it cannot be
   determined at runtime.

   va_end is used to clean up.

   Multiple traversals,  each bracketed by va_start  ...  va_end,
   are possible.

MTB-762-01                                   C Runtime Extensions


NAME:  vprintf, vfprintf, vsprintf -  print formatted output of a
varargs argument list


   #include <stdio.h>
   #include <varargs.h>

   int vprintf (format, ap)
   char *format;
   va_list ap;

   int vfprintf  (stream, format , ap)
   FILE *stream;
   char *format;
   va_list ap;

   int vsprintf (s, format, ap)
   char *s, *format;
   va_list ap;


   vprintf,  vfprintf,  and  vsprintf  are  the  same  as printf,
   fprintf,  and  sprintf  respectively,  except  that instead of
   being  called with  a variable  number or  arguments, they are
   called with an argument list as defined by varargs.