dg_sysctl(2) DG/UX R4.11MU05 dg_sysctl(2)
NAME
dg_sysctl - perform system configuration and control functions
SYNOPSIS
#include <sys/dg_sysctl.h>
int dg_sysctl (cmd, arg)
unsigned int cmd;
void * arg;
DESCRIPTION
Use dg_sysctl 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/dg_sysctl.h>.
Commands
The cmd parameters are listed and explained below.
DG_SYSCTL_CONFIGURE_DEVICE
Configure a device; arg gives the device's name in DG/UX common
device specification (CDS) format.
DG_SYSCTL_DECONFIGURE_DEVICE
Deconfigure (remove) a device; arg gives the device's name in CDS
format.
DG_SYSCTL_NAME_TO_DEVICE
Get the number of a device; arg gives the device's name in CDS
format.
DG_SYSCTL_DEVICE_TO_NAME
Get the name of a device in CDS format; arg gives the device's
number.
DG_SYSCTL_SET_BOOT_PATH
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
DG_SYSCTL_SET_AUTOREBOOT 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.
DG_SYSCTL_GET_BOOT_PATH
Find out the current boot command line. The boot path is put into
arg.
DG_SYSCTL_SET_DUMP_DEVICE
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.
DG_SYSCTL_GET_DUMP_DEVICE
Get the name of the current dump device in CDS format. The name is
put into arg.
DG_SYSCTL_SET_AUTOREBOOT
Specify whether the system should attempt automatic reboot after a
system halt. For auto-reboot, set arg to
DG_SYSCTL_REBOOT_AFTER_PANIC; for the default (no auto-reboot),
set arg to DG_SYSCTL_HALT_AFTER_PANIC.
DG_SYSCTL_GET_AUTOREBOOT
Find out the current auto-reboot setting; arg is set to either
DG_SYSCTL_REBOOT_AFTER_PANIC or DG_SYSCTL_HALT_AFTER_PANIC.
DG_SYSCTL_SET_DUMP_START
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 DG_SYSCTL_ASK_FOR_DUMP. If you want the system to dump
memory to a writable medium in the dump device without asking, set
arg to DG_SYSCTL_AUTO_DUMP. To bypass the memory dump option, set
arg to DG_SYSCTL_SKIP_DUMP.
DG_SYSCTL_GET_DUMP_START
Get the current dump-start setting; arg is set to
DG_SYSCTL_ASK_FOR_DUMP, DG_SYSCTL_AUTO_DUMP, or
DG_SYSCTL_SKIP_DUMP.
DG_SYSCTL_SET_DUMP_LEVEL
Specify the level of a memory dump after a system halt. Set arg to
DG_SYSCTL_DUMP_KERNEL_FRAMES to select kernel frames only (the
default), or to DG_SYSCTL_DUMP_ALL_FRAMES for all memory frames.
DG_SYSCTL_GET_DUMP_LEVEL
Get the current dump-level setting; arg is set to either
DG_SYSCTL_DUMP_KERNEL_FRAMES or DG_SYSCTL_DUMP_ALL_FRAMES.
DG_SYSCTL_SET_AUTO_POWEROFF
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
DG_SYSCTL_AUTO_POWEROFF). To turn the feature off, set arg to
DG_SYSCTL_SKIP_POWEROFF. The auto-poweroff setting has no effect
when the system is halted abnormally (e.g., because the system has
detected a serious error).
DG_SYSCTL_GET_AUTO_POWEROFF
Find out the current auto-poweroff setting; arg is set to either
DG_SYSCTL_AUTO_POWEROFF or DG_SYSCTL_SKIP_POWEROFF.
DG_SYSCTL_GET_BOOT_PATH_DEFAULT
Find out the default boot command line that was used to boot the
currently running system. The boot path is put into arg.
DG_SYSCTL_GET_DUMP_DEVICE_DEFAULT
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.
DG_SYSCTL_GET_AUTOREBOOT_DEFAULT
Find out the default auto-reboot setting that was in effect when
the currently running system was booted; arg is set to either
DG_SYSCTL_REBOOT_AFTER_PANIC or DG_SYSCTL_HALT_AFTER_PANIC.
DG_SYSCTL_GET_DUMP_START_DEFAULT
Find out the default dump-start setting that was in effect when
the currently running system was booted; arg is set to
DG_SYSCTL_ASK_FOR_DUMP, DG_SYSCTL_AUTO_DUMP, or
DG_SYSCTL_SKIP_DUMP.
DG_SYSCTL_GET_DUMP_LEVEL_DEFAULT
Find out the default dump-level setting that was in effect when
the currently running system was booted; arg is set to either
DG_SYSCTL_DUMP_KERNEL_FRAMES or DG_SYSCTL_DUMP_ALL_FRAMES.
DG_SYSCTL_GET_AUTO_POWEROFF_DEFAULT
Find out the default auto-poweroff setting that was in effect when
the currently running system was booted; arg is set to either
DG_SYSCTL_AUTO_POWEROFF or DG_SYSCTL_SKIP_POWEROFF.
DG_SYSCTL_USER_REQUESTED_PANIC
The command used to cause a user requested system halt. The arg
must be a pointer to a packet of type
dg_sysctl_user_requested_panic which contains the information used
to customize the user halt.
Automatic Halt Dumps
If you set the dump start state to DG_SYSCTL_AUTO_DUMP, 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
DG_SYSCTL_HALT_AFTER_PANIC and DG_SYSCTL_ASK_FOR_DUMP, 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
dg_sysctl_user_requested_panic 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
debugger_state to either DG_SYSCTL_ENTER_DEBUGGER_ON_PANIC or
DG_SYSCTL_DO_NOT_ENTER_DEBUGGER_ON_PANIC 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
user_message_ptr field of the packet. The message can be up to
DG_SYSCTL_MAX_USER_PANIC_MESSAGE_LENGTH characters long, including
the NULL. If no user message is desired, set the user_message_ptr 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 dg_sysctl command is defined by
the literal DG_SYSCTL_MAX_NAME_LENGTH, which includes space for the
trailing NULL.
EXAMPLES
For the DG_SYSCTL_CONFIGURE_DEVICE, DG_SYSCTL_DECONFIGURE_DEVICE,
DG_SYSCTL_SET_BOOT_PATH, and DG_SYSCTL_SET_DUMP_DEVICE commands, you
specify the address of a string as the arg parameter. Here are some
examples of using these commands:
#include <sys/dg_sysctl.h>
int status;
status = dg_sysctl (DG_SYSCTL_CONFIGURE_DEVICE,
"duart(1)");
status = dg_sysctl (DG_SYSCTL_DECONFIGURE_DEVICE,
"inen()");
status = dg_sysctl (DG_SYSCTL_SET_BOOT_PATH,
"sd(cisc(),0)/dgux -3");
status = dg_sysctl (DG_SYSCTL_SET_DUMP_DEVICE,
"st(insc(),4)");
status = dg_sysctl (DG_SYSCTL_SET_DUMP_DEVICE,
"vdm_dump(sd(cisc(),0),sys_dump)");
For the DG_SYSCTL_NAME_TO_DEVICE command, allocate and fill in a
dg_sysctl_name_to_device packet and pass its address as the arg
parameter. The device number will be returned in the device_number
field of the packet. Here is an example of using this command:
#include <sys/dg_sysctl.h>
int status;
struct dg_sysctl_name_to_device name_to_device_pkt;
name_to_device_pkt.device_name = "sd(insc(),0)";
status = dg_sysctl (DG_SYSCTL_NAME_TO_DEVICE,
&name_to_device_pkt);
printf ("device number is %d\n",
name_to_device_pkt.device_number);
For the DG_SYSCTL_DEVICE_TO_NAME command, allocate and fill in a
dg_sysctl_device_to_name 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 device_name field
of the packet. Here is an example of using this command:
#include <sys/dg_sysctl.h>
int status;
char returned_device_name [DG_SYSCTL_MAX_NAME_LENGTH];
struct dg_sysctl_device_to_name device_to_name_pkt;
device_to_name_pkt.device_number = 393216;
device_to_name_pkt.device_name = returned_device_name;
device_to_name_pkt.max_name_length = DG_SYSCTL_MAX_NAME_LENGTH;
status = dg_sysctl (DG_SYSCTL_DEVICE_TO_NAME,
&device_to_name_pkt);
printf ("device name is '%s'\n",
returned_device_name);
For the DG_SYSCTL_GET_BOOT_PATH and DG_SYSCTL_GET_BOOT_PATH_DEFAULT
commands, allocate and fill in a dg_sysctl_get_boot_path 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 boot_path field of the packet. Here is an example of using
these commands:
#include <sys/dg_sysctl.h>
int status;
char returned_boot_path [DG_SYSCTL_MAX_NAME_LENGTH];
struct dg_sysctl_get_boot_path get_boot_path_pkt;
get_boot_path_pkt.boot_path = returned_boot_path;
get_boot_path_pkt.max_name_length = DG_SYSCTL_MAX_NAME_LENGTH;
status = dg_sysctl (DG_SYSCTL_GET_BOOT_PATH,
&get_boot_path_pkt);
printf ("boot path is '%s'\n",
returned_boot_path);
For the DG_SYSCTL_GET_DUMP_DEVICE and
DG_SYSCTL_GET_DUMP_DEVICE_DEFAULT commands, allocate and fill in a
dg_sysctl_get_dump_device 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 dump_device_name
field of the packet. Here is an example of using these commands:
#include <sys/dg_sysctl.h>
int status;
char returned_dump_device [DG_SYSCTL_MAX_NAME_LENGTH];
struct dg_sysctl_get_dump_device get_dump_device_pkt;
get_dump_device_pkt.dump_device_name = returned_dump_device;
get_dump_device_pkt.max_name_length = DG_SYSCTL_MAX_NAME_LENGTH;
status = dg_sysctl (DG_SYSCTL_GET_DUMP_DEVICE,
&get_dump_device_pkt);
printf ("dump device name is '%s'\n",
returned_dump_device);
For these commands, specify the address of an unsigned int as the arg
parameter: DG_SYSCTL_SET_AUTOREBOOT, DG_SYSCTL_GET_AUTOREBOOT,
DG_SYSCTL_SET_DUMP_START, DG_SYSCTL_GET_DUMP_START,
DG_SYSCTL_SET_DUMP_LEVEL, DG_SYSCTL_GET_DUMP_LEVEL,
DG_SYSCTL_SET_AUTO_POWEROFF, DG_SYSCTL_GET_AUTO_POWEROFF,
DG_SYSCTL_GET_AUTOREBOOT_DEFAULT, DG_SYSCTL_GET_DUMP_START_DEFAULT,
DG_SYSCTL_GET_DUMP_LEVEL_DEFAULT, and
DG_SYSCTL_GET_AUTO_POWEROFF_DEFAULT.
For the set commands, you fill in the unsigned int with the desired
value before calling dg_sysctl. For the get commands, dg_sysctl
returns the current setting of the system option in the unsigned int.
Here are some examples of using these commands:
#include <sys/dg_sysctl.h>
int status;
unsigned int option_value;
option_value = DG_SYSCTL_REBOOT_AFTER_PANIC;
status = dg_sysctl (DG_SYSCTL_SET_AUTOREBOOT,
&option_value);
status = dg_sysctl (DG_SYSCTL_GET_AUTOREBOOT,
&option_value);
printf ("auto-reboot option value is %u\n",
option_value);
For the DG_SYSCTL_USER_REQUESTED_PANIC command, allocate and fill in
a dg_sysctl_user_requested_panic packet and pass its address as the
arg parameter. Here is an example of using this command:
#include <sys/dg_sysctl.h>
int status;
struct dg_sysctl_user_requested_panic user_panic_pkt;
user_panic_pkt.debugger_state =
DG_SYSCTL_DO_NOT_ENTER_DEBUGGER_ON_PANIC;
user_panic_pkt.user_message_ptr = "After transaction write";
status = dg_sysctl (DG_SYSCTL_USER_REQUESTED_PANIC,
&user_panic_pkt);
For more details on the dg_sysctl 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: DG_SYSCTL_NAME_TO_DEVICE,
DG_SYSCTL_DEVICE_TO_NAME, DG_SYSCTL_GET_BOOT_PATH,
DG_SYSCTL_GET_DUMP_DEVICE, DG_SYSCTL_GET_AUTOREBOOT,
DG_SYSCTL_GET_DUMP_START, DG_SYSCTL_GET_DUMP_LEVEL,
DG_SYSCTL_GET_AUTO_POWEROFF, DG_SYSCTL_GET_BOOT_PATH_DEFAULT,
DG_SYSCTL_GET_DUMP_DEVICE_DEFAULT, DG_SYSCTL_GET_AUTOREBOOT_DEFAULT,
DG_SYSCTL_GET_DUMP_START_DEFAULT, DG_SYSCTL_GET_DUMP_LEVEL_DEFAULT,
and DG_SYSCTL_GET_AUTO_POWEROFF_DEFAULT.
Only a user with appropriate privilege may execute these commands:
DG_SYSCTL_CONFIGURE_DEVICE, DG_SYSCTL_DECONFIGURE_DEVICE,
DG_SYSCTL_SET_BOOT_PATH, DG_SYSCTL_SET_DUMP_DEVICE,
DG_SYSCTL_SET_AUTOREBOOT, DG_SYSCTL_SET_DUMP_START,
DG_SYSCTL_SET_DUMP_LEVEL, DG_SYSCTL_SET_AUTO_POWEROFF, and
DG_SYSCTL_USER_REQUESTED_PANIC.
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 cap_defaults(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
appropriate_privilege(5) man page for more information.
RETURN VALUE
0 The dg_sysctl 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 dg_sysctl 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
dg_sysctl(1M), admpdisk(1M), halt(1M), reboot(1M), reboot(2),
uadmin(2), appropriate_privilege(5).
cap_defaults(5).
Licensed material--property of copyright holder(s)