'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH g2.sys3b @(#)sys3b	40.23 of 11/30/89
.\" Copyright 1989 AT&T
.nr X 
.if \nX=0 .ds x} sys3b 2 "" "\&"
.if \nX=1 .ds x} sys3b 2 ""
.if \nX=2 .ds x} sys3b 2 "" "\&"
.if \nX=3 .ds x} sys3b "" "" "\&"
.TH \*(x}
'\" t
.SH NAME
\f4sys3b\f1 \- machine-specific functions
.SH SYNOPSIS
\f4#include <sys/sys3b.h>\f1
.PP
\f4int sys3b(int cmd, ...);\f1
.SH DESCRIPTION
\f4sys3b\f1
implements machine-specific functions.
The
.I cmd
argument determines the function performed.
The type and number of arguments expected depends on the function.
.SS "Command \f4GRNFLASH\fP"
When
.I cmd
is \f4GRNFLASH\fP, no arguments are expected.  This
function starts the green LED flashing.  
This command is
only available to the super-user.
.SS "Command \f4GRNON\fP"
When
.I cmd
is \f4GRNON\fP, no arguments are expected.  This
function turns the green LED to a solid on state.
This command is available only to the super-user.
.SS "Command \f4RNVR\fP"
When
.I cmd
is \f4RNVR\fP, an argument of type \f4const struct
nvparams \(**\fP is expected.
.PP
.RS
.ft 4
.nf
struct nvparams{
	char \(**addr;
	char \(**data;
	unsigned short cnt;
	};
.fi
.ft 1
.RE
.PP
This function reads \f4cnt\fP bytes at address \f4addr\fP in
NVRAM (non-volatile RAM) into address data.
This command is available only to the super-user.
.SS "Command \f4RTODC\fP"
When
.I cmd
is \f4RTODC\fP, an argument of type \f4struct todc \(**\fP
is expected. 
.PP
.RS
.ft 4
.nf
struct todc {
	short htenths;  short hsecs;  short hmins;
	short hhours;  short hdays;  short hweekday;
	short hmonth;  short hyear;
	};
.fi
.ft 1
.RE
.PP
This function reads the hardware time-of-day clock and returns
the data in the structure referred to by the argument.
This command is available only to the super-user.
.SS "Command \f4S3BSYM\fP"
When
.I cmd
is \f4S3BSYM\fP, the symbol table created when a new bootable operating system is
configured may be accessed.
The symbols available via this command
are defined in one of two places: 
the driver routines loaded or
the variable specifications in the files in the 
\f4/etc/master.d\f1
directory.
Two arguments are expected:  the first must be a pointer to a buffer
into which the symbol table is copied, and the second must be an integer
containing the total size of the buffer.
The format of the symbol table is:
.PP
.RS
.nf
.ft 4
int size;         /\(** symbol size in bytes \(**/
int count;        /\(** total number of symbols \(**/
.sp 0.5
                  /\(** for each symbol: \(**/
char name[];      /\(** name of symbol, padded \(**/
                  /\(** with '\e0' to next \(**/
                  /\(** sizeof(long) boundary \(**/
char symbol[1];   /\(** long value;  value of symbol \(**/
.ft 1
.fi
.RE
.PP
The \f4S3BSVAL\f1 macro in \f4sys/sys3b.h\f1 takes a pointer 
to a symbol name in the table and returns its value.
The \f4S3BNXTSYM\f1 macro takes 
a pointer to a symbol name in the table and returns a pointer to 
the next entry.
Include \f4sys/inline.h\f1 to use these macros.
.PP
Typically, the symbol table would be retrieved with two calls to
\f4sys3b\fP.
First, the size of the symbol table is obtained by calling
\f4sys3b\fP
with a buffer of one integer.
This integer is then used to obtain a buffer large enough
to contain the entire symbol table.
The second invocation of
\f4sys3b\fP
with this newly obtained buffer retrieves the entire symbol table.
.PP
.RS
.ft 4
.nf
#include <sys/sys3b.h>
.sp 0.5
int            size;           /\(** size of buffer needed \(**/
struct s3bsym  \(**buffer;        /\(** buffer pointer \(**/
.sp 0.5
sys3b( S3BSYM, (struct s3bsym \(**) &size, sizeof(size) );
.br
buffer = (struct s3bsym \(**) malloc( size );
sys3b( S3BSYM, buffer, size );
.fi
.ft 1
.RE
.SS "Command \f4S3BCONF\fP"
When
.I cmd
is \f4S3BCONF\fP, the configuration table created during the configuration of a
new bootable operating system may be accessed.
This table contains the names and locations of the devices supported by
the currently running UNIX system,
the names of all software modules included in the system,
and the names of all devices in the EDT that were ignored.
Two arguments are expected:  the first must be a pointer to a buffer
into which the configuration table is copied, and the second must be an integer
containing the total size of the buffer.
The format of the configuration table is:
.PP
.RS 
.ta .5i 1.4i
.nf
.ft 4
int	ndev;	/\(** total number of entries \(**/
.sp 0.5
		/\(** for each entry ... \(**/
long	timestamp;	/\(**   f_timdat from file header \(**/
char	name[14];	/\(**   name of device/module \(**/
char	flag;	/\(**   configuration information \(**/
		/\(**     0x80: device ignored \(**/
		/\(**     0x40: name[\|] is a driver \(**/
		/\(**     0x20: name[\|] is a software module \(**/
char	board;	/\(** local bus address of device \(**/
.ta
.ft 1
.fi
.RE
.PP
Typically, the configuration table would be retrieved with two calls to
\f4sys3b\fP.
First, the number of entries is obtained by calling
\f4sys3b\fP
with a buffer of one integer.
This integer is then used to calculate and obtain a buffer large enough
to contain the entire configuration table.
The second invocation of
\f4sys3b\fP
with this newly obtained buffer retrieves the configuration table.
.PP
.RS
.ft 4
.nf
#include <sys/sys3b.h>
.sp 0.5
.ta .5i 1.75i
int	count;	/\(** total number of devices \(**/
int	size;	/\(** size of buffer needed \(**/
struct	s3bconf \(**buffer;	/\(** buffer pointer \(**/
.ta
.sp 0.5
sys3b( S3BCONF, (struct s3bconf \(**)&count, sizeof(count));
size = sizeof(int);
size += count \(** sizeof(struct s3bc);
buffer = (struct s3bconf \(**)malloc(size);
sys3b(S3BCONF, buffer, size);
.fi
.ft 1
.RE
.SS "Command \f4S3BBOOT\fP"
When
.I cmd
is \f4S3BBOOT\fP, the timestamp and path name of the program last used to
bootstrap the machine may be accessed.
The path name of the \f4a.out\fP format file which was booted, and the timestamp
from the file header [see
\f4a.out\fP(4)]
are saved.
One argument is expected:  a pointer to a buffer into which the
information is copied.
The format of this information is:
.PP
.RS
.ta .5i 1.75i
\f4long	timestamp;	/\(** f_timdat from file header \(**/\f1
.br
\f4char	path[100];	/\(** path name \(**/\f1
.ta
.RE
.PP
This information would be retrieved with a single call to
\f4sys3b\fP.
.PP
.RS
\f4#include <sys/sys3b.h>\f1
.PP
\f4struct s3bboot buffer;  /\(** buffer \(**/\f1
.PP
\f4sys3b(S3BBOOT, &buffer);\f1
.RE
.SS "Command \f4S3BAUTO\fP"
When
.I cmd
is \f4S3BAUTO\fP, no arguments are expected.
This function returns a boolean value in answer to the question,
``Was the operating system reconfigured during the last boot, or
was an existing bootable operating system booted?''
The value returned is zero if an existing bootable (such as
\f4/stand/stand/unix\f1 or \f4/stand/unix\f1) was booted.
The integer value 1 is returned if the bootable operating system was
configured during the preceding boot process.
The value is undefined 
if the system was booted
in ``magic mode.''
This command
is available only to the super-user.
.SS "Command \f4S3BFPHW\fP"
When
.I cmd
is \f4S3BFPHW\fP,
an indication of whether or not a
.SM MAU
is present is returned.
(See the \f2Introduction\f1
to this manual for a description of the \s-1MAU\s0.)
One argument, the address of an \f4int\fP,
is expected.
On return from the system call,
this \f4int\fP contains a 1 if a
.SM MAU
is present or a 0 if a
.SM MAU
is not present.
If the address of the \f4int\fP is not valid
(for example, not word aligned, not user accessible)
\f4EFAULT\f1 is returned.
.PP
The following example determines whether a
.SM MAU
is present:
.PP
.RS
\f4#include <sys/sys3b.h>\f1
.PP
\f4int mau_present;\f1
.br
\f4sys3b(S3BFPHW, &mau_present);\f1
.RE
.PP
If this command succeeds,
it returns 0 to the calling process.
The call fails and returns \-1
if one or more of the following is true:
.TP 12
\f4EFAULT\fP
\f4mau_present\fP is not an integer.
.TP
\f4EFAULT\fP
\f4&mau_present\fP is an invalid address.
.SS "Command \f4S3BSWPI\fP"
Note:  This \f2cmd\f1 is available only with
UNIX System V Release 2.1 and Release 3 software.
Its function is subsumed by the \f4swap\fP command; see \f4swap\fP(1M).
.P
When
.I cmd
is \f4S3BSWPI\fP,
individual swapping areas 
may be added, deleted or 
the current areas determined.
The address of
an appropriately primed swap buffer
is passed as the only argument.
(Refer to the
\f4sys/swap.h\fP
header file for details of loading the buffer.) 
.PP
The format of the swap buffer is:
.PP
.RS
.ft 4
.nf
.ta 1.0i 2i
struct swapint {
     char	si_cmd;	/\(**command: list, add, delete\(**/
     char	\(**si_buf;	/\(**swap file path pointer\(**/
     int	si_swplo;	/\(**start block\(**/
     int	si_nblks;	/\(**swap size\(**/
}
.fi
.ft 1
.RE
.PP
Note that the add and delete options of the command may 
be exercised only by the super-user.
.PP
Typically, a swap area is added by a single call to 
\f4sys3b\fP. 
First, the swap buffer is primed with
appropriate entries for the structure members.
Then 
\f4sys3b\fP
is invoked.
.PP
.RS 
.ta 2i
\f4#include <sys/sys3b.h>\f1
.br
\f4#include <sys/swap.h>\f1
.PP
\f4struct swapint swapbuf;	/\(**swap into buffer ptr\(**/\f1
.PP
\f4sys3b(S3BSWPI, &swapbuf);\f1
.RE
.PP
If this command succeeds, it returns 0 to the calling process.
It fails and returns \-1 if one or more of the 
following is true:
.TP 12
\f4EFAULT\fP
\f2swapbuf\f1 points to an invalid address.
.TP
\f4EFAULT\fP
\f2swapbuf\f4.si_buf\f1 points to an invalid address.
.TP
\f4ENOTBLK\fP
The swap area specified is not a block special device.
.TP
\f4EEXIST\fP
The swap area specified has already been added.
.TP
\f4ENOSPC\fP
Too many swap areas are in use (if adding).
.TP
\f4ENOMEM\fP
The swap area specified is the last remaining swap area.
.TP
\f4ENOMEM\fP
There is no place to put swapped pages when deleting a swap area.
.TP
\f4EINVAL\fP
An argument is invalid.
.br
.ne 1i
.SS "Command \f4STIME\fP"
When
.I cmd
is \f4STIME\fP, an argument of type \f4long\fP is
expected.  This function sets the system time and date.  The
argument contains the time as measured in seconds from
00:00:00 UTC January 1, 1970.  
This command is available only to the super-user.
.SS "Command \f4WNVR\fP"
When
.I cmd
is \f4WNVR\fP, an argument of type \f4struct nvparams \(**\fP
is expected (see command \f4RNVR\fP).  This function writes
\f2cnt\f1 bytes into address \f2addr\f1 in NVRAM
(non-volatile RAM) from address \f2data\f1.
This command is available only to the super-user.
.SS "Command \f4S3BTRAPLOCORE\fP"
Prior to release 4.0, user processes could read low memory
(for example, read accesses using NULL pointers
were permitted from user programs).
When \f2cmd\f1 is \f4S3BTRAPLOCORE\fP, user level
access permission on low core memory can be changed and user
accesses of low core memory can be trapped.
Only read access is affected;  user level write access to low
core is not allowed under any circumstances.
.P
A single argument of type \f4int\fP is expected.
This argument may have one of the following
four values, defined in <\f4sys/sys3b.h>\fP:
.TP
\f4S3BTLC_DISABLE\fP
Disable low core trapping.
Read accesses to low core are allowed from user processes.
.TP
\f4S3BTLC_SIGNAL\fP
Trap low core accesses.
Any user process which attempts to read low core will be sent a
\f4SIGSEGV\fP signal with \f4si_code\fP set to \f4SEGV_MAPERR\fP.
.TP
\f4S3BTLC_PRINT\fP
Trap low core accesses.
Any user process which attempts to read low core will be sent a
\f4SIGSEGV\fP signal with \f4si_code\fP set to \f4SEGV_MAPERR\fP.
In addition, a message will be printed on the system console each
time a process attempts to read low core.
.TP
\f4S3BTLC_STATUS\fP
Return current state of low core trapping.
The state of low core trapping is unchanged.
.PP
If this command succeeds, it returns one of \f4S3BTLC_DISABLE\fP,
\f4S3BTLC_SIGNAL\fP, \f4S3BTLC_PRINT\fP, to indicate the setting
of low core protection prior to the call.
The command fails and returns \-1 if one or more of 
the following is true:
.TP .7i
\f4EPERM\fP
The caller is not super-user (not required for \f4S3BTLC_STATUS\fP).
.TP
\f4EINVAL\fP
An argument is invalid.
.br
.ne 2i
.SH DIAGNOSTICS
On success, \f4sys3b\fP returns a value that depends on
.I cmd\^
as follows:
.RS
.TP 1.0i
\f4S3BSYM\fP
A value of zero.
.PD 0
.TP
\f4S3BCONF\fP
A value of zero.
.TP
\f4S3BBOOT\fP
A value of zero.
.TP
\f4S3BAUTO\fP
A value of zero if an existing bootable operating system (such as
\f4/stand/stand/unix\f1 or \f4/stand/unix\f1) was last booted.
A value of one if a new bootable operating system was configured during the
last boot process.
.TP
\f4S3BTRAPLOCORE\fP
Returns the setting of low core protection prior to the call.
.RE
.PD
.P
Otherwise, a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
When
.I cmd
is invalid, 
\f4errno\fP
is set to \f4EINVAL\fP on return.
.SH SEE ALSO
\f4sync\fP(2), \f4a.out\fP(4).
.sp .2
\f4cunix\fP(1M),
\f4swap\fP(1M),
in the \f2System Administrator's Reference Manual\f1.
.Ee
