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:
DGHowe@System-M
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
1. ABORT
NAME: abort - generate an IOT fault
SYNOPSIS:
int abort ( )
DESCRIPTION:
abort first closes all open files if possible, then causes an
IOT signal to be sent to the process. This usually results in
termination.
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
2. ACCESS
NAME: access - determine accessibility of a file
SYNOPSIS:
int acess (path, amode)
char *path;
int amode;
DESCRIPTION:
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
3. ALARM
NAME: alarm - set a process alarm clock
SYNOPSIS:
unsigned alarm (sec)
unsigned sec;
DESCRIPTION:
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
SYNOPSIS
cb [ -s ] [ -j ] [ -1 leng ] [ file . . .]
DESCRIPTION
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
5. CLOCK
NAME: clock - report CPU time used
SYNOPSIS
long clock ( )
DESCRIPTION
Clock returns the amount of CPU time (in microseconds) used
since the first call to clock.
MTB-762-01 C Runtime Extensions
6. CTIME
NAME: ctime, localtime, gmtime, asctime, tzset - convert date
and time to string
SYNOPSIS:
#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 ( )
DESCRIPTION
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
uses.
Asctime converts a "tm" structure to a 26-character string, as
shown in the above example, and returns a pointer to the
string.
C Runtime Extensions MTB-762-01
7. ENVIRON
NAME: environ - user environment
DESCRIPTION
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.
TZ
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
SYNOPSIS
char *getenv (name)
char *name
DESCRIPTION
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
SYNOPSIS
int putenv (string)
char *string;
DESCRIPTION
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
file
SYNOPSIS:
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[ ];
DESCRIPTION
Exec in all its forms transfers control to the specified new
process.
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.
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
pointer.
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
9. FCNTL
NAME: fcntl - file control
SYNOPSIS
#include <fcntl.h>
int fcntl (fildes, cmd, arg)
int fildes, cmd, arg;
DESCRIPTION
Fcntl provides for control over open files. Fildes is an open
file descriptor obtained from a creat, open or fcntl system
call.
The commands available are:
F_GETFL
Get file status flags.
F_SETFL
set file status flags to arg. Only certain flags can be set;
see fcntl.
C Runtime Extensions MTB-762-01
10. GETCWD
NAME: getcwd - get path-name of current working directory
SYNOPSIS
char *getcwd (buf, size)
char *buf;
int size;
DESCRIPTION
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
free.
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
12. GETLOGIN
NAME: getlogin - get login name
SYNOPSIS
char *getlogin ( );
DESCRIPTION
Getlogin returns a pointer to the login name.
MTB-762-01 C Runtime Extensions
13. GETOPT
NAME: getopt - get option letter from argument vector
SYNOPSIS
int getopt (argc, argv, optstring)
int argc;
char **argv, *opstring;
extern char *optarg;
extern int optind, opterr;
DESCRIPTION
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
getopt.
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
14. GETPID
NAME: getpid - get process ID.
SYNOPSIS
int getpid ()
DESCRIPTION
Getpid returns the process ID of the calling process.
MTB-762-01 C Runtime Extensions
15. GETUID
NAME: getuid - get user ID.
SYNOPSIS:
unsigned short getuid ()
DESCRIPTION
Getuid returns the user ID of the calling process.
C Runtime Extensions MTB-762-01
16. IOCTL
NAME: ioctl - control device
SYNOPSIS
ioctl (fildes, request, arg)
int fildes, request;
DESCRIPTION
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
<termio.h>:
#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:
TCGETA
Get the parameters associated with the terminal and store
in the termio structure referenced by arg.
TCSETA
Set the parameters associated with the terminal from the
structure referenced by arg. The change is immediate.
TCSETAW
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
TCSETAF
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:
TCSBRK
Wait for the output to drain. If arg is 0, then send a
break.
TCXONC
Start/stop control. If arg is 0, suspend output; if 1,
restart suspended output.
TCFLSH
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
SYNOPSIS
int link (path, *path2;
char *path1, *path2;
DESCRIPTION
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
19. PERROR
NAME: perror, errno, sys_errlist, sys_nerr - system error
messages
SYNOPSIS
void perror (s)
char *s;
extern int errno;
extern char *sys_errlist[ ];
extern int sys_nerr;
DESCRIPTION
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
SYNOPSIS
int rand ( )
void srand (seed)
unsigned seed;
DESCRIPTION
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
SYNOPSIS
unsigned sleep (seconds)
unsigned seconds;
DESCRIPTION
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
SYNOPSIS
#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;
DESCRIPTION
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
23. STRING
NAME: strpbrk, strspn, strcspn, strtok, - string operations
SYNOPSIS
#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;
DESCRIPTION
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
returned.
C Runtime Extensions MTB-762-01
24. STRTOD
NAME: strtod - convert string to double-precision number
SYNOPSIS
double strtod (str, ptr)
char *str, **ptr;
DESCRIPTION
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
25. STRTOL
NAME: strtol, atol, atoi - convert string to interger
SYNOPSIS
long strtol (str, ptr, base)
char *str **ptr;
int base;
DESCRIPTION
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
SYNOPSIS
void swab (from, to, nbytes)
char *from, *to;
int nbytes;
DESCRIPTION
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
SYNOPSIS
#include <sys/types.h>
#include <sys/times.h>
long times (buffer)
struct tms *buffer;
DESCRIPTION
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
28. VARARGS
NAME: varargs - handle variable argument list
SYNOPSIS
#include <varargs.h>
va_alist
va_dcl
void va_start(pvar)
va_list pvar;
type va_arg(pvar, type)
va_list pvar;
void va_end(pvar)
va list pvar;
DESCRIPTION
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
list.
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
29. VPRINTF
NAME: vprintf, vfprintf, vsprintf - print formatted output of a
varargs argument list
SYNOPSIS
#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;
DESCRIPTION
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.