dg_sysctl(2) DG/UX R4.11MU05 dg_sysctl(2)
NAME
dgsysctl - perform system configuration and control functions
SYNOPSIS
#include <sys/dgsysctl.h>
int dgsysctl (cmd, arg)
unsigned int cmd;
void * arg;
DESCRIPTION
Use dgsysctl to perform a configuration or control task specified by
cmd; arg is the address of an information packet used by and/or
filled in by cmd. The various commands and the types of their
corresponding argument packets are defined and described in
<sys/dgsysctl.h>.
Commands
The cmd parameters are listed and explained below.
DGSYSCTLCONFIGUREDEVICE
Configure a device; arg gives the device's name in DG/UX common
device specification (CDS) format.
DGSYSCTLDECONFIGUREDEVICE
Deconfigure (remove) a device; arg gives the device's name in CDS
format.
DGSYSCTLNAMETODEVICE
Get the number of a device; arg gives the device's name in CDS
format.
DGSYSCTLDEVICETONAME
Get the name of a device in CDS format; arg gives the device's
number.
DGSYSCTLSETBOOTPATH
Set the boot command line that will be used by reboot(2) or
uadmin(2), or after a system halt if auto-reboot is set (see
DGSYSCTLSETAUTOREBOOT below); arg gives the path of the kernel
image to be booted. (Do not include the SCM boot command in the
path.)
The default boot path is what was used when the system was last
booted. If arg is empty or all spaces, the boot path saved by the
SCM will be used.
The specified path will be used for future automatic reboots of
the system until you change the boot path. A path specified from
the SCM during manual rebooting overrides this path.
DGSYSCTLGETBOOTPATH
Find out the current boot command line. The boot path is put into
arg.
DGSYSCTLSETDUMPDEVICE
Set the device to be used for a system dump when a halt occurs;
arg gives the device name in CDS format. The default dump device
is the device specified for the DUMP variable in the system
configuration file.
The dump device may be a tape device or a virtual disk. For tape
devices, use the tape drive's device specification (e.g.,
"st(insc(),4)"). For virtual disks, use a string of the form
"vdm_dump(physical-disk,virtual-disk)". For example,
"vdm_dump(sd(insc(),0),sys_dump)" is a valid virtual disk dump
device specification.
DGSYSCTLGETDUMPDEVICE
Get the name of the current dump device in CDS format. The name is
put into arg.
DGSYSCTLSETAUTOREBOOT
Specify whether the system should attempt automatic reboot after a
system halt. For auto-reboot, set arg to
DGSYSCTLREBOOTAFTERPANIC; for the default (no auto-reboot),
set arg to DGSYSCTLHALTAFTERPANIC.
DGSYSCTLGETAUTOREBOOT
Find out the current auto-reboot setting; arg is set to either
DGSYSCTLREBOOTAFTERPANIC or DGSYSCTLHALTAFTERPANIC.
DGSYSCTLSETDUMPSTART
Specify how or whether a memory dump is started after a system
halt. If you want the operator to be prompted (the default) set
arg to DGSYSCTLASKFORDUMP. If you want the system to dump
memory to a writable medium in the dump device without asking, set
arg to DGSYSCTLAUTODUMP. To bypass the memory dump option, set
arg to DGSYSCTLSKIPDUMP.
DGSYSCTLGETDUMPSTART
Get the current dump-start setting; arg is set to
DGSYSCTLASKFORDUMP, DGSYSCTLAUTODUMP, or
DGSYSCTLSKIPDUMP.
DGSYSCTLSETDUMPLEVEL
Specify the level of a memory dump after a system halt. Set arg to
DGSYSCTLDUMPKERNELFRAMES to select kernel frames only (the
default), or to DGSYSCTLDUMPALLFRAMES for all memory frames.
DGSYSCTLGETDUMPLEVEL
Get the current dump-level setting; arg is set to either
DGSYSCTLDUMPKERNELFRAMES or DGSYSCTLDUMPALLFRAMES.
DGSYSCTLSETAUTOPOWEROFF
Specify whether the system should power itself off automatically
after a normal shutdown. Not all systems support auto-poweroff.
For systems that do, auto-poweroff is the default (arg is
DGSYSCTLAUTOPOWEROFF). To turn the feature off, set arg to
DGSYSCTLSKIPPOWEROFF. The auto-poweroff setting has no effect
when the system is halted abnormally (e.g., because the system has
detected a serious error).
DGSYSCTLGETAUTOPOWEROFF
Find out the current auto-poweroff setting; arg is set to either
DGSYSCTLAUTOPOWEROFF or DGSYSCTLSKIPPOWEROFF.
DGSYSCTLGETBOOTPATHDEFAULT
Find out the default boot command line that was used to boot the
currently running system. The boot path is put into arg.
DGSYSCTLGETDUMPDEVICEDEFAULT
Get the name of the default dump device in CDS format. This is the
device name that was specified in the kernel configuration for the
currently running system. The name is put into arg.
DGSYSCTLGETAUTOREBOOTDEFAULT
Find out the default auto-reboot setting that was in effect when
the currently running system was booted; arg is set to either
DGSYSCTLREBOOTAFTERPANIC or DGSYSCTLHALTAFTERPANIC.
DGSYSCTLGETDUMPSTARTDEFAULT
Find out the default dump-start setting that was in effect when
the currently running system was booted; arg is set to
DGSYSCTLASKFORDUMP, DGSYSCTLAUTODUMP, or
DGSYSCTLSKIPDUMP.
DGSYSCTLGETDUMPLEVELDEFAULT
Find out the default dump-level setting that was in effect when
the currently running system was booted; arg is set to either
DGSYSCTLDUMPKERNELFRAMES or DGSYSCTLDUMPALLFRAMES.
DGSYSCTLGETAUTOPOWEROFFDEFAULT
Find out the default auto-poweroff setting that was in effect when
the currently running system was booted; arg is set to either
DGSYSCTLAUTOPOWEROFF or DGSYSCTLSKIPPOWEROFF.
DGSYSCTLUSERREQUESTEDPANIC
The command used to cause a user requested system halt. The arg
must be a pointer to a packet of type
dgsysctluserrequestedpanic which contains the information used
to customize the user halt.
Automatic Halt Dumps
If you set the dump start state to DGSYSCTLAUTODUMP, note these
points:
· You must ensure that the dump medium is always available and
ready to be used. For tape drives, this means there must be a
write-enabled tape that is large enough to hold the memory
dump in the drive at all times. For virtual disks, this means
the virtual disk must exist prior to the halt, must be large
enough to hold the memory dump, and must not be used for
anything else (e.g., do not build a file system on it or use
it for swapping). Moreover, the virtual disk must be a single
partition physical disk.
If you need to use the dump device for some other purpose
temporarily, you should first disable automatic halt dumps or
change the dump device to some other available device. After
you are finished using the device, you can re-enable automatic
halt dumps or switch the dump device back. If you do not make
either of these temporary changes and a halt occurs, the
medium in the dump device will be overwritten.
· If a halt occurs and the dump device cannot be opened (e.g.,
no tape in the drive, virtual disk doesn't exist, or a device
error), the dump will be skipped instead.
· If the dump cannot be completed (e.g., due to a hard error on
the tape, or a tape or virtual disk that is too small to hold
the dump), the dump will be abandoned; no opportunity is
provided to restart the dump with a new dump device.
Dump Level
This parameter does not apply to diskless workstations. Diskless
workstations always dump all memory frames.
Unless requested by Data General to change the dump level to all
frames, leave it set to the default (dump kernel frames only).
Kernel-frame dumps are smaller and faster, and usually contain all
the information needed to understand the cause of a halt.
Operator Shutdowns
If you use the hot key sequence to cause a system halt or use the "s
1000" SCM command to initiate an operator shutdown, the auto-reboot
and dump start states will be reset to their default values of
DGSYSCTLHALTAFTERPANIC and DGSYSCTLASKFORDUMP, respectively.
This will give the operator complete control over the system during
the halt processing.
User Requested Halts
User requested system halts are frequently used to test recovery
algorithms to see how they handle system halts. The halt that is
caused is identical to any real system halt, including honoring the
autoreboot and autodump states. The user requested halt happens
immediately. There is no return from the system call after the halt
happens.
The arg must be a pointer to a packet of type
dgsysctluserrequestedpanic which contains the information used to
customize the user halt.
You can control whether the kernel debugger (if linked into the
kernel) is entered when a user requested halt happens by setting the
debuggerstate to either DGSYSCTLENTERDEBUGGERONPANIC or
DGSYSCTLDONOTENTERDEBUGGERONPANIC in the packet.
You can optionally have a message you specify printed with the DG/UX
halt message to help identify why the user halt is happening. This
is useful if you have several user halts in your application so you
can tell which one is which.
Put a pointer to the text string you want printed in the
usermessageptr field of the packet. The message can be up to
DGSYSCTLMAXUSERPANICMESSAGELENGTH characters long, including
the NULL. If no user message is desired, set the usermessageptr to
NULL.
You can cause a user requested halt from a shell command line by
using the halt(1M) command.
String Length
The maximum name length used by any dgsysctl command is defined by
the literal DGSYSCTLMAXNAMELENGTH, which includes space for the
trailing NULL.
EXAMPLES
For the DGSYSCTLCONFIGUREDEVICE, DGSYSCTLDECONFIGUREDEVICE,
DGSYSCTLSETBOOTPATH, and DGSYSCTLSETDUMPDEVICE commands, you
specify the address of a string as the arg parameter. Here are some
examples of using these commands:
#include <sys/dgsysctl.h>
int status;
status = dgsysctl (DGSYSCTLCONFIGUREDEVICE,
"duart(1)");
status = dgsysctl (DGSYSCTLDECONFIGUREDEVICE,
"inen()");
status = dgsysctl (DGSYSCTLSETBOOTPATH,
"sd(cisc(),0)/dgux -3");
status = dgsysctl (DGSYSCTLSETDUMPDEVICE,
"st(insc(),4)");
status = dgsysctl (DGSYSCTLSETDUMPDEVICE,
"vdmdump(sd(cisc(),0),sysdump)");
For the DGSYSCTLNAMETODEVICE command, allocate and fill in a
dgsysctlnametodevice packet and pass its address as the arg
parameter. The device number will be returned in the devicenumber
field of the packet. Here is an example of using this command:
#include <sys/dgsysctl.h>
int status;
struct dgsysctlnametodevice nametodevicepkt;
nametodevicepkt.devicename = "sd(insc(),0)";
status = dgsysctl (DGSYSCTLNAMETODEVICE,
&nametodevicepkt);
printf ("device number is %d\n",
nametodevicepkt.devicenumber);
For the DGSYSCTLDEVICETONAME command, allocate and fill in a
dgsysctldevicetoname packet and pass its address as the arg
parameter. The device name will be returned in a string you
allocate. Pass the address of that string in the devicename field
of the packet. Here is an example of using this command:
#include <sys/dgsysctl.h>
int status;
char returneddevicename [DGSYSCTLMAXNAMELENGTH];
struct dgsysctldevicetoname devicetonamepkt;
devicetonamepkt.devicenumber = 393216;
devicetonamepkt.devicename = returneddevicename;
devicetonamepkt.maxnamelength = DGSYSCTLMAXNAMELENGTH;
status = dgsysctl (DGSYSCTLDEVICETONAME,
&devicetonamepkt);
printf ("device name is '%s'\n",
returneddevicename);
For the DGSYSCTLGETBOOTPATH and DGSYSCTLGETBOOTPATHDEFAULT
commands, allocate and fill in a dgsysctlgetbootpath packet and
pass its address as the arg parameter. The boot path will be
returned in a string you allocate. Pass the address of that string
in the bootpath field of the packet. Here is an example of using
these commands:
#include <sys/dgsysctl.h>
int status;
char returnedbootpath [DGSYSCTLMAXNAMELENGTH];
struct dgsysctlgetbootpath getbootpathpkt;
getbootpathpkt.bootpath = returnedbootpath;
getbootpathpkt.maxnamelength = DGSYSCTLMAXNAMELENGTH;
status = dgsysctl (DGSYSCTLGETBOOTPATH,
&getbootpathpkt);
printf ("boot path is '%s'\n",
returnedbootpath);
For the DGSYSCTLGETDUMPDEVICE and
DGSYSCTLGETDUMPDEVICEDEFAULT commands, allocate and fill in a
dgsysctlgetdumpdevice packet and pass its address as the arg
parameter. The dump device will be returned in a string you
allocate. Pass the address of that string in the dumpdevicename
field of the packet. Here is an example of using these commands:
#include <sys/dgsysctl.h>
int status;
char returneddumpdevice [DGSYSCTLMAXNAMELENGTH];
struct dgsysctlgetdumpdevice getdumpdevicepkt;
getdumpdevicepkt.dumpdevicename = returneddumpdevice;
getdumpdevicepkt.maxnamelength = DGSYSCTLMAXNAMELENGTH;
status = dgsysctl (DGSYSCTLGETDUMPDEVICE,
&getdumpdevicepkt);
printf ("dump device name is '%s'\n",
returneddumpdevice);
For these commands, specify the address of an unsigned int as the arg
parameter: DGSYSCTLSETAUTOREBOOT, DGSYSCTLGETAUTOREBOOT,
DGSYSCTLSETDUMPSTART, DGSYSCTLGETDUMPSTART,
DGSYSCTLSETDUMPLEVEL, DGSYSCTLGETDUMPLEVEL,
DGSYSCTLSETAUTOPOWEROFF, DGSYSCTLGETAUTOPOWEROFF,
DGSYSCTLGETAUTOREBOOTDEFAULT, DGSYSCTLGETDUMPSTARTDEFAULT,
DGSYSCTLGETDUMPLEVELDEFAULT, and
DGSYSCTLGETAUTOPOWEROFFDEFAULT.
For the set commands, you fill in the unsigned int with the desired
value before calling dgsysctl. For the get commands, dgsysctl
returns the current setting of the system option in the unsigned int.
Here are some examples of using these commands:
#include <sys/dgsysctl.h>
int status;
unsigned int optionvalue;
optionvalue = DGSYSCTLREBOOTAFTERPANIC;
status = dgsysctl (DGSYSCTLSETAUTOREBOOT,
&optionvalue);
status = dgsysctl (DGSYSCTLGETAUTOREBOOT,
&optionvalue);
printf ("auto-reboot option value is %u\n",
optionvalue);
For the DGSYSCTLUSERREQUESTEDPANIC command, allocate and fill in
a dgsysctluserrequestedpanic packet and pass its address as the
arg parameter. Here is an example of using this command:
#include <sys/dgsysctl.h>
int status;
struct dgsysctluserrequestedpanic userpanicpkt;
userpanicpkt.debuggerstate =
DGSYSCTLDONOTENTERDEBUGGERONPANIC;
userpanicpkt.usermessageptr = "After transaction write";
status = dgsysctl (DGSYSCTLUSERREQUESTEDPANIC,
&userpanicpkt);
For more details on the dgsysctl system call input and output
arguments for each command, see the <sys/dg_sysctl.h> include file.
ACCESS CONTROL
Any user may execute these commands: DGSYSCTLNAMETODEVICE,
DGSYSCTLDEVICETONAME, DGSYSCTLGETBOOTPATH,
DGSYSCTLGETDUMPDEVICE, DGSYSCTLGETAUTOREBOOT,
DGSYSCTLGETDUMPSTART, DGSYSCTLGETDUMPLEVEL,
DGSYSCTLGETAUTOPOWEROFF, DGSYSCTLGETBOOTPATHDEFAULT,
DGSYSCTLGETDUMPDEVICEDEFAULT, DGSYSCTLGETAUTOREBOOTDEFAULT,
DGSYSCTLGETDUMPSTARTDEFAULT, DGSYSCTLGETDUMPLEVELDEFAULT,
and DGSYSCTLGETAUTOPOWEROFFDEFAULT.
Only a user with appropriate privilege may execute these commands:
DGSYSCTLCONFIGUREDEVICE, DGSYSCTLDECONFIGUREDEVICE,
DGSYSCTLSETBOOTPATH, DGSYSCTLSETDUMPDEVICE,
DGSYSCTLSETAUTOREBOOT, DGSYSCTLSETDUMPSTART,
DGSYSCTLSETDUMPLEVEL, DGSYSCTLSETAUTOPOWEROFF, and
DGSYSCTLUSERREQUESTEDPANIC.
On a system with DG/UX information security, appropriate privilege is
defined as having one or more specific capabilities enabled in the
effective capability set of the calling process. See capdefaults(5)
for the default capability for this system call.
On a traditional DG/UX system, appropriate privilege is granted by
having an effective UID of 0 (root). See the
appropriateprivilege(5) man page for more information.
RETURN VALUE
0 The dgsysctl operation was successful.
-1 An error occurred. errno is set to indicate the error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EPERM A process called dgsysctl and attempted to execute a
restricted command without having appropriate privilege.
ENXIO An attempt was made to configure a device that was already
configured.
ENXIO An attempt was made to deconfigure, get the name of, or get
the device number of a device that is not configured.
ENXIO An attempt to configure or deconfigure a device failed for
an unknown reason.
ENOMEM There was insufficient kernel memory available to execute
cmd.
EFAULT arg or a pointer in the packet points to an invalid
address.
EFAULT An attempt was made to configure or deconfigure a device,
get the device number of a device from its name, set the
boot command line, or to set the dump device name, but the
string specified was too long.
EBUSY An attempt was made to deconfigure a busy or
undeconfigurable device.
EINVAL cmd is not one of the valid commands described above.
EINVAL An attempt was made to configure or deconfigure a device,
get the device number of a device from its name, or to set
the dump device name, but the device name did not conform
to the DG/UX Common Device Specification Format.
EINVAL An attempt was made to get the name of a device from its
device number, the boot command line, or the dump device
name, but not enough string storage was allocated to
receive the name.
EINVAL An attempt was made to set the auto-reboot, dump start,
dump level, or auto-poweroff state, but the value pointed
to by arg was not one of the valid values for the commands
specified in <sys/dg_sysctl.h>.
EOPNOTSUPP
An attempt was made to set the automatic poweroff state on
a system that does not support the feature.
SEE ALSO
dgsysctl(1M), admpdisk(1M), halt(1M), reboot(1M), reboot(2),
uadmin(2), appropriateprivilege(5).
capdefaults(5).
Licensed material--property of copyright holder(s)