pmlib_request_parameter Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

pmlib_request_parameter Subroutine

Purpose

Queries and controls the PM system parameters.

Library

PM (Power Management) Library (libpm.a)

Syntax

#include <pmlib.h>

int pmlib_request_parameter(ctrl, arg);
int ctrl;
caddr_t *arg;

The pmlib_request_parameter subroutines queries and changes the PM system or devices parameters. Any of these queries can be called by any user, but the set can be called only by root.

Parameters

ctrl

Determines the action to be taken by the pmlib_request_parameter subroutine and is one of the following values:

PMLIB_QUERY_SYSTEM_IDLE_TIME: Queries system idle timer.
PMLIB_SET_SYSTEM_IDLE_TIME: Sets system idle timer.
PMLIB_QUERY_DEVICE_INFO: Queries device information.
PMLIB_SET_DEVICE_INFO: Sets device information.
PMLIB_QUERY_SYSTEM_IDLE_ACTION: Queries action for system idle.
PMLIB_SET_SYSTEM_IDLE_ACTION: Sets action for system idle.
PMLIB_QUERY_LID_CLOSE_ACTION: Queries action for lid close.
PMLIB_SET_LID_CLOSE_ACTION: Sets action for lid close.
PMLIB_QUERY_MAIN_SWITCH_ACTION: Queries action for main switch.
PMLIB_SET_MAIN_SWITCH_ACTION: Sets action for main switch.
PMLIB_QUERY_LOW_BATTERY_ACTION: Queries action for low battery.
PMLIB_SET_LOW_BATTERY_ACTION: Sets action for low battery.
PMLIB_QUERY_PERMISSION: Queries the action permitted to any user.
PMLIB_SET_PERMISSION: Sets the action permitted to any user.
PMLIB_QUERY_BEEP: Queries whether beep is enabled or not.
PMLIB_SET_BEEP: Sets whether beep is enabled or not.
PMLIB_QUERY_RINGING_RESUME: Queries if ringing resume is enabled or not.
PMLIB_SET_RINGING_RESUME: Sets if ringing resume is enabled or not.
PMLIB_QUERY_RESUME_TIME: Queries resume time.
PMLIB_SET_RESUME_TIME: Sets resume time.
PMLIB_QUERY_DURATION_TO_HIBERNATION: Queries duration to hibernation.
PMLIB_SET_DURATION_TO_HIBERNATION: Sets duration to hibernation.
PMLIB_QUERY_SPECIFIED_TIME: Queries specified time.
PMLIB_SET_SPECIFIED_TIME: Sets specified time.
PMLIB_QUERY_SPECIFIED_TIME_ACTION: Queries action for specified time.
PMLIB_SET_SPECIFIED_TIME_ACTION: Sets action for specified time.
PMLIB_QUERY_DEVICE_NUMBER: Queries number of PM aware devices.
PMLIB_QUERY_DEVICE_NAMES: Queries the list of names of PM aware devices.
PMLIB_QUERY_SUPPORTED_STATES: Queries the system states supported.
PMLIB_QUERY_KILL_LFT_SESSION: Queries if LFT session is terminated.
PMLIB_SET_KILL_LFT_SESSION: Sets if LFT session is terminated.
PMLIB_QUERY_KILL_TTY_SESSION: Queries if TTY session is terminated.
PMLIB_SET_KILL_TTY_SESSION: Sets if TTY session is terminated.
PMLIB_QUERY_PASSWD_ON_RESUME: Queries if resume password is required.
PMLIB_SET_PASSWD_ON_RESUME: Sets if resume password is required.
PMLIB_QUERY_KILL_SYNCD: Queries if syncd is terminated at standby.
PMLIB_SET_KILL_SYNCD: Sets if syncd is terminated at system standby.

When ctrl is PMLIB_QUERY_SYSTEM_IDLE_TIMER, arg points to an integer that is the system idle timer value when function is returned.

When ctrl is PMLIB_SET_SYSTEM_IDLE_TIMER, arg points to an integer that is the system idle timer value to set. The system idle timer value should be within the range from 60 to 7200. If 0 is set, the system-idle check is disabled.

When ctrl is PMLIB_QUERY_DEVICE_INFO, arg points to the following pmlib_device_info_t structure. The device name needs to be specified in the name[16] member. Then, mode, idle_time, standby_time, idle_time1 and idle_time2 members are set when function is returned.

typedef struct _pmlib_device_info{
   char name[16];      /*name of device*/
   int mode;           /*device mode*/
   int attribute;      /*device attribute*/
   int idle_time;      /*idle timer value during system PM enable*/
   int standby_time;   /*idle timer value during system standby*/
   int idle_time1;     /*idle timer value for DPMS suspend*/
   int idle_time2;     /*idle timer value for DPMS off*/
   char reserved[24];  /*reserved area for future use*/
} pmlib_device_info_t;

When ctrl is PMLIB_SET_DEVICE_INFO, arg points to pmlib_device_info_t structure, and the devicename to name[16]. idle_time, standby_time, idle_time1 and idle_time2 members need to be set. The value of idle_time is within the range from 60 to 7200. If idle_time, standby_time, idle_time1, or idle_time2 is set to -1, the current value is not changed.

When ctrl is PMLIB_QUERY_SYSTEM_IDLE_ACTION, arg points to an integer that is the action for system-idle timer expiration when the function is returned. Possible values for action are as follows:

PMLIB_NONE	State doesn't change
PMLIB_SYSTEM_FULL_ON	Full on
PMLIB_SYSTEM_ENABLE	PM enable
PMLIB_SYSTEM_STANDBY	Stand by
PMLIB_SYSTEM_SUSPEND	Suspend
PMLIB_SYSTEM_HIBERNATION	Hibernation
PMLIB_SYSTEM_SHUTDOWN	Shutdown

When ctrl is PMLIB_SET_SYSTEM_IDLE_ACTION, arg points to an integer that is the action to be set for system-idle timer expiration. The value for action should be one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_QUERY_LID_CLOSE_ACTION, arg points to an integer that is the action for lid close when the function is returned. Possible values for action are one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_SET_LID_CLOSE_ACTION, arg points to an integer that is the action to be set for lid close. The value for action should be one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_QUERY_MAIN_SWITCH_ACTION, arg points to an integer that is the action for the main switch when the function is returned. Possible values for action are one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_SET_MAIN_SWITCH_ACTION, arg points to an integer that is the action to set for the main switch. The value for action should be one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_QUERY_LOW_BATTERY_ACTION, arg points to an integer that is the action for the low battery when the function is returned. Possible values for action are one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_SET_LOW_BATTERY_ACTION, arg points to an integer that is the action to be set for the low battery. The value for action should be one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_QUERY_PERMISSION, arg points to an integer that is the action for allowed to any user when the function is returned. Possible values for action are bit-wise OR of following values:

PMLIB_SYSTEM_FULL_ON	Full on
PMLIB_SYSTEM_ENABLE	PM enable
PMLIB_SYSTEM_STANDBY	Standby
PMLIB_SYSTEM_SUSPEND	Suspend
PMLIB_SYSTEM_HIBERNATION	Hibernation
PMLIB_SYSTEM_SHUTDOWN	Shutdown

When ctrl is PMLIB_SET_PERMISSION, arg points to an integer that is the action to be set for allowed to any user. Possible values for action are bit-wise OR of following values:

PMLIB_SYSTEM_FULL_ON	Full on
PMLIB_SYSTEM_ENABLE	PM enable
PMLIB_SYSTEM_STANDBY	Standby
PMLIB_SYSTEM_SUSPEND	Suspend
PMLIB_SYSTEM_HIBERNATION	Hibernation
PMLIB_SYSTEM_SHUTDOWN	Shutdown

When ctrl is PMLIB_QUERY_BEEP, arg points to an integer that is PMLIB_ON or PMLIB_OFF for beep on/off.

When ctrl is PMLIB_SET_BEEP, arg points to an integer that is PMLIB_ON or PMLIB_OFF to set for beep on/off.

When ctrl is PMLIB_QUERY_RINGING_RESUME, arg points to an integer that is PMLIB_ON or PMLIB_OFF for ringing resume on/off when the function is returned.

When ctrl is PMLIB_SET_RINGING_RESUME, arg points to an integer that is PMLIB_ON or PMLIB_OFF for ringing resume on/off.

When ctrl is PMLIB_QUERY_RESUME_TIME, arg points to an integer that is the time for resume when the function is returned. The integer value is the time in seconds since 00:00:00 GMT, January 1, 1970.

When ctrl is PMLIB_SET_RESUME_TIME, arg points to an integer that is the time for resume to be set. The integer value should be the time in seconds since 00:00:00 GMT, January 1, 1970.

When ctrl is PMLIB_QUERY_DURATION_TO_HIBERNATION, arg points to an integer that is the duration to hibernation in seconds when the function is returned.

When ctrl is PMLIB_SET_DURATION_TO_HIBERNATION, arg points to an integer that is the duration to hibernation in seconds to be set.

When ctrl is PMLIB_QUERY_SPECIFIED_TIME, arg points to an integer that is the specified time when the function is returned. The integer value is the time in seconds since 00:00:00 GMT, January 1, 1970.

When ctrl is PMLIB_SET_SPECIFIED_TIME, arg points to an integer that is the specified time to be set. The integer value should be the time in seconds since 00:00:00 GMT, January 1, 1970.

When ctrl is PMLIB_QUERY_SPECIFIED_TIME_ACTION, arg points to an integer that is the action for the specified time when the function is returned. Possible values for action is one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_SET_SPECIFIED_TIME_ACTION, arg points to an integer that is the action to be set for the specified time. The value for action should be one of the values described at PMLIB_QUERY_SYSTEM_IDLE_ACTION.

When ctrl is PMLIB_QUERY_DEVICE_NUMBER, arg points to an integer that is the number of PM aware device drivers when the function is returned.

When ctrl is PMLIB_QUERY_DEVICE_NAMES, arg points to the head of array of name[16] that is the names of PM aware device drivers when the function is returned.

When ctrl is PMLIB_QUERY_SUPPORTED_STATES, arg points to an integer that is the action supported when the function is returned. The integer is bit-wise OR of following values:

PMLIB_SYSTEM_FULL_ON	Full on
PMLIB_SYSTEM_ENABLE	PM enable
PMLIB_SYSTEM_STANDBY	Standby
PMLIB_SYSTEM_SUSPEND	Suspend
PMLIB_SYSTEM_HIBERNATION	Hibernation
PMLIB_SYSTEM_SHUTDOWN	Shutdown

When ctrl is PMLIB_QUERY_KILL_LFT_SESSION, arg points to an integer that is PMLIB_ON or PMLIB_OFF to show if LFT session is terminated.

When ctrl is PMLIB_SET_KILL_LFT_SESSION, arg points to an integer that is PMLIB_ON or PMLIB_OFF to set if LFT session is terminated.

When ctrl is PMLIB_QUERY_KILL_TTY_SESSION, arg points to an integer that is PMLIB_ON or PMLIB_OFF to show if TTY sessions are terminated.

When ctrl is PMLIB_SET_KILL_TTY_SESSION, arg points to an integer that is PMLIB_ON or PMLIB_OFF to set if TTY sessions are terminated.

When ctrl is PMLIB_QUERY_PASSWD_ON_RESUME, arg points to an integer that is PMLIB_ON or PMLIB_OFF to show if resume password is required.

When ctrl is PMLIB_SET_PASSWD_ON_RESUME, arg points to an integer that is PMLIB_ON or PMLIB_OFF to set if resume password is required.

When ctrl is PMLIB_QUERY_KILL_SYNCD, arg points to an integer that is PMLIB_ON or PMLIB_OFF to show if sync daemon is terminated during system standby.

When ctrl is PMLIB_SET_KILL_SYNCD, arg points to an integer that is PMLIB_ON or PMLIB_OFF to set if sync daemon is terminated during system standby.

Return Values

Upon successful completion, PMLIB_SUCCESS is returned. If the pmlib_request_state subroutine fails, PMLIB_ERROR is returned and errno variable is set to an error code.

Error Codes

ESRCH	PM daemon is not running.
EINVAL	Invalid argument.
EPERM	Missing privilege.
ENOMEM	Insufficient storage.

Implementation Specifics

The pmlib_request_parameter subroutine is part of the Base Operation System (BOS) Runtime.

Related Information

The pmlib_get_event_notice subroutine, pmlib_request_state subroutine, pmlib_request_battery subroutine, pmlib_register_application subroutine.