[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 1

pmlib_request_state Subroutine

Purpose

Requests system state change.

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 subroutine, pmlib_request_battery subroutine, pmlib_request_parameter subroutine, pmlib_register_application subroutine.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]