Technical Reference: Base Operating System and Extensions, Volume 1

pmlib_request_state Subroutine

Library

PM (Power Management) Library (libpm.a)

Syntax

#include <pmlib.h>

int pmlib_request_state (ctrl, pms);
int ctrl;
pmlib_state_t *pms;

Parameters

ctrl

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

PMLIB_REQUEST_STATE: Requests to change system state.
PMLIB_QUERY_STATE: Requests to query system state.
PMLIB_QUERY_ERROR: Requests to query error of system state change.
PMLIB_CONFIRM: Confirms system state change.

pms

Points to the following pmlib_state_t structure:

typedef struct _pmlib_state {
   int state;     /*system state for set/query*/
   int error;     /*error value for query error*/
   pid_t pid;     /*process id of application which
                   prevented the state change*/
   char name[16];  /*name of application or PM aware DD
                   which prevented the state change*/
} pmlib_state_t;

When ctrl is PMLIB_REQUEST_STATE, set one of the following state values to pms.state:

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_STATE, one of state values described at PMLIB_REQUEST_STATE is set to pms.state when the function returns. PM aware DD's name is also returned if it rejects the PM command.

When ctrl is PMLIB_QUERY_ERROR, one of the following error values are set to pms.error:

PMLIB_NO_ERROR	No error.
PMLIB_ERROR_REJECT_BY_DEVICE	Device rejected to change state.
PMLIB_ERROR_REJECT_BY_APPL	Application rejected to change state.
PMLIB_ERROR_REJECT_BY_SYSTEM	System does not allow to change state.
PMLIB_ERROR_REJECTED_BY_HIB_VOL	Hibernation volume is invalid.
PMLIB_ERROR_REJECTED_BY_EVENT	A event prevented the state change.
PMLIB_ERROR_INVALID_PRIVILEGE	Caller was not allowed to change state.
PMLIB_ERROR_DEVICE_ERROR	A device rejected to change mode.
PMLIB_ERROR_OTHERS	Other error occurred.

If an application caused system state change failure, the process id of that application is set to pms.pid, and the name set to pms.name when the function returns.

When ctrl is PMLIB_CONFIRM, set one of the following state values to pms.state.

PMLIB_SYSTEM_CHANGE_OK	OK to change the system state.
PMLIB_SYSTEM_CHANGE_NO	No change to the system state.

Description

The pmlib_request_state subroutine is called to request to change PM system state, request to query PM system state, request to query the error of PM system state change, or request to confirm PM system state change. Non-root user can request to change state only if the specified action an the action within the range allowed to any user.

Return Values

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

Error Codes

ESRCH	PM daemon is not running.
EINVAL	Invalid argument.
EPERM	Missing privilege.
EBUSY	State change processing has already been started.

Implementation Specifics

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

Related Information

The pmlib_get_event_notice (pmlib_get_event_notice Subroutine) subroutine, pmlib_request_battery (pmlib_request_battery Subroutine) subroutine, pmlib_request_parameter (pmlib_request_parameter Subroutine) subroutine, pmlib_register_application (pmlib_register_application Subroutine) subroutine.