dg_sysctl(2) DG/UX 5.4R3.00 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 panic 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.
Licensed material--property of copyright holder(s) 1
dg_sysctl(2) DG/UX 5.4R3.00 dg_sysctl(2)
DGSYSCTLSETDUMPDEVICE
Set the device to be used for a system dump when a panic 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 panic. 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
panic. 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 panic. 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
Licensed material--property of copyright holder(s) 2
dg_sysctl(2) DG/UX 5.4R3.00 dg_sysctl(2)
DGSYSCTLSKIPPOWEROFF. The auto-poweroff setting has no effect
when the system is halted abnormally (e.g., because of a panic).
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.
Automatic Panic 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 panic, 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 panic dumps or
change the dump device to some other available device. After
Licensed material--property of copyright holder(s) 3
dg_sysctl(2) DG/UX 5.4R3.00 dg_sysctl(2)
you are finished using the device, you can re-enable automatic
panic dumps or switch the dump device back. If you do not
make either of these temporary changes and a panic occurs, the
medium in the dump device will be overwritten.
⊕ If a panic 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 panic.
Operator Shutdowns
If you use the hot key sequence to cause a system panic 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 panic processing.
String Length
The maximum string 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");
Licensed material--property of copyright holder(s) 4
dg_sysctl(2) DG/UX 5.4R3.00 dg_sysctl(2)
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>
Licensed material--property of copyright holder(s) 5
dg_sysctl(2) DG/UX 5.4R3.00 dg_sysctl(2)
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;
Licensed material--property of copyright holder(s) 6
dg_sysctl(2) DG/UX 5.4R3.00 dg_sysctl(2)
optionvalue = DGSYSCTLREBOOTAFTERPANIC;
status = dgsysctl (DGSYSCTLSETAUTOREBOOT,
&optionvalue);
status = dgsysctl (DGSYSCTLGETAUTOREBOOT,
&optionvalue);
printf ("auto-reboot option value is %u\n",
optionvalue);
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 the superuser may execute these commands:
DGSYSCTLCONFIGUREDEVICE, DGSYSCTLDECONFIGUREDEVICE,
DGSYSCTLSETBOOTPATH, DGSYSCTLSETDUMPDEVICE,
DGSYSCTLSETAUTOREBOOT, DGSYSCTLSETDUMPSTART,
DGSYSCTLSETDUMPLEVEL, and DGSYSCTLSETAUTOPOWEROFF.
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 being the superuser.
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,
Licensed material--property of copyright holder(s) 7
dg_sysctl(2) DG/UX 5.4R3.00 dg_sysctl(2)
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), reboot(1M), reboot(2), uadmin(2).
Licensed material--property of copyright holder(s) 8