man pages section 3: Extended Library Functions, Volume 1

Exit Print View

Updated: July 2014
 
 

v12n_get_parent_env(3EXT)

Name

v12n, v12n_get_current_env, v12n_get_env_name, v12n_get_env_prop, v12n_get_prop_name, v12n_get_parent_env, v12n_list_env_props, v12n_list_envs, v12n_list_supported_envs, v12n_capabilities, v12n_domain_roles, v12n_domain_name, v12n_domain_uuid, v12n_ctrl_domain, v12n_chassis_serialno - return virtualization environment information

Synopsis

cc [ flag... ] file... -lv12n [ 
library... ]
#include <libv12n.h>


v12n_env_t * v12n_get_current_env(void);
v12n_env_t * v12n_get_parent_env(void);
char * v12n_get_env_prop(v12n_env_t *environment, v12n_prop_t property);
v12n_env_t ** v12n_list_supported_envs(void);
v12n_env_t ** v12n_list_envs(void);
v12n_env_t ** v12n_list_env_props(v12n_env_t *environment
);
const char *v12n_get_prop_name(v12n_prop_t property);
void v12n_free_env(v12n_env_t *environment)
v12n_env_t * v12n_copy_env(v12n_env_t *environment
)

Description

v12n_env_t is an opaque type. The supported functions, return values, and errors are described below:

v12n_get_current_env()

Returns the current environment. See below for the list of possible environment names.

v12n_get_parent_env()

Returns the parent environment. Currently, the parent environment can only be detected from a non-global zone. See below for the list of possible environment names.

v12n_get_env_prop()

Returns a string representation of a requested property for a given environment. The returned string must be freed by the caller.

v12n_list_supported_envs()

Fills out a NULL-terminated array with all supported environments. The array and its contents must be freed by the caller. NULL is returned on error.

v12n_list_envs()

Fills out a NULL-terminated array with all known environments. The array and its contents must be freed by the caller. NULL is returned on error.

v12n_list_env_props()

Fills out a NULL-terminated array with all known property types for the given environment. The array must be freed by the caller. NULL is returned on error.

v12n_get_prop_name()

Returns a string representation of a virtual environment property.

v12n_free_env()

Frees the storage associated with an v12n_env_t.

v12n_copy_env()

Copies the supplied v12n_env_t. A new v12n_env_t is returned.

Environments

Environments

libv12n knows about the following environments. As some are SPARC or x86 specific, they may not be available on both platforms.

Type
Name
Platform
Unknown
unknown
Both
Kernel-based Virtual Machine
kvm
x86
Logical Domains
logical-domain
SPARC
Non-Global Zone
non-global-zone
Both
Kernel Zone
kernel-zone
Both
VMware
vmware
x86
VirtualBox
virtualbox
x86
Xen
xen
x86

Properties

Properties

libv12n knows about the following properties. Properties depend both on the class as well as the name of the environment.

Type
Class
Name
V12N_PROP_NAME
(all)
name
V12N_PROP_CLASS
(all)
class
V12N_PROP_LDOMS_CHASSIS
current
chassis-serial-number
V12N_PROP_LDOMS_CONTROL_NAME
current
control-name
V12N_PROP_LDOMS_NAME
current
domain-name
V12N_PROP_LDOMS_ROLE_CONTROL
current
control-role
V12N_PROP_LDOMS_ROLE_IO
current
io-role
V12N_PROP_LDOMS_ROLE_ROOT
current
root-role
V12N_PROP_LDOMS_ROLE_SERVICE
current
service-role
V12N_PROP_LDOMS_UUID
current
uuid

Legacy

Legacy
int v12n_capabilities();
int v12n_domain_roles();
int v12n_domain_uuid(uuid_t uuid);
size_t v12n_domain_name(char *buf, size_t 
buflen);
size_t v12n_ctrl_domain(char *buf, size_t 
buflen);
size_t v12n_chassis_serialno(char *buf, size_t 
buflen);

The v12n_capabilities() function returns the virtualization capabilities mask of the current domain. The virtualization capabilities bit mask consists of the following values:

Value
Description
V12N_CAP_SUPPORTED
Virtualization is supported on this domain.
V12N_CAP_ENABLED
Virtualization is enabled on this domain.
V12N_CAP_IMPL_LDOMS
Logical Domains is the supported virtualization implementation.

The v12n_domain_roles() function returns the virtualization domain role mask. The virtualization domain role mask consists of the following values:

Value
Description
V12N_ROLE_CONTROL
If the virtualization implementation is Logical Domains, and this bit is one, the current domain is a control domain. If this bit is zero, the current domain is a guest domain.
V12N_ROLE_IO
Current domain is an I/O domain.
V12N_ROLE_SERVICE
Current domain is a service domain.
V12N_ROLE_ROOT
Current domain is a root I/O domain.

The v12n_domain_uuid() function stores the universally unique identifier (UUID) for the current virtualization domain in the uuid argument. See the libuuid(3LIB) manual page.

The v12n_domain_name() function stores the name of the current virtualization domain in the location specified by buf. buflen specifies the size in bytes of the buffer. If the buffer is too small to hold the complete null-terminated name, the first buflen bytes of the name are stored in the buffer. A buffer of size V12N_NAME_MAX is sufficient to hold any domain name. If buf is NULL or buflen is 0, the name is not copied into the buffer.

The v12n_ctrl_domain() function stores the control domain or dom0 network node name of the current domain in the location specified by buf. Note that a domain's control domain is volatile during a domain migration. The information returned by this function might be stale if the domain was in the process of migrating. buflen specifies the size in bytes of the buffer. If the buffer is too small to hold the complete null-terminated name, the first buflen bytes of the name are stored in the buffer. A buffer of size V12N_NAME_MAX is sufficient to hold the control domain node name string. If buf is NULL or buflen is 0, the name is not copied into the buffer.

The v12n_chassis_serialno() function stores the chassis serial number of the platform on which the current domain is running in the location specified by buf. Note that the chassis serial number is volatile during a domain migration. The information returned by this function might be stale if the domain was in the process of migrating. buflen specifies the size in bytes of the buffer. If the buffer is too small to hold the complete null-terminated name, the first buflen bytes of the name are stored in the buffer. A buffer of size V12N_NAME_MAX is sufficient to hold any chassis serial number string. If buf is NULL or buflen is 0, the name is not copied into the buffer.

Return Values

On successful completion, the v12n_get_current_env(), v12n_get_parent_env() and v12n_copy_env() functions return an opaque pointer to a v12n_env_t representing an environment. Otherwise, the v12n_get_current_env() function returns NULL and sets errno to indicate the error.

On successful completion, the v12n_get_env_prop() returns a string holding the property value. the v12n_get_current_env() function returns NULL and sets errno to indicate the error.

On successful completion, the v12n_list_supported_envs(), v12n_list_envs(), and v12n_list_env_props() functions return an array. Otherwise, these functions return NULL and sets errno to indicate the error.

On successful completion, the v12n_capabilties() and v12n_domain_roles() functions return a non-negative bit mask. Otherwise, the v12n_domain_roles() function returns -1 and sets errno to indicate the error.

On successful completion, the v12n_domain_uuid() function returns 0. Otherwise, the v12n_domain_uuid() function returns -1 and sets errno to indicate the error.

On successful completion, the v12n_domain_name(), v12n_ctrl_domain(), and v12n_chassis_serialno() functions return the buffer size required to hold the full non-terminated string. Otherwise, these functions return -1 and set errno to indicate the error.

Errors

The v12n_get_current_env() and v12n_get_parent_env () functions fail if:

ENOMEM

Insufficient memory to complete the operation.

EACCES

The calling process has insufficient privilege for accessing device configuration data (x86 only).

ENXIO

The devinfo(7D) driver is not installed properly (x86 only).

The v12n_list_supported_envs() function will fail if:

ENOMEM

Insufficient memory to complete the operation.

The v12n_get_env_prop() function will fail if:

EINVAL

The specified environment or property does not exist.

ENOMEM

Insufficient memory to complete the operation.

For the logical domain properties:

V12N_PROP_LDOMS_CHASSIS

See v12n_chassis_serialno()

V12N_PROP_LDOMS_CONTROL_NAME

See v12n_ctrl_domain()

V12N_PROP_LDOMS_NAME

See v12n_domain_name()

V12N_PROP_LDOMS_ROLE_CONTROL

See v12n_domain_roles()

V12N_PROP_LDOMS_ROLE_IO

See v12n_domain_roles()

V12N_PROP_LDOMS_ROLE_ROOT

See v12n_domain_roles()

V12N_PROP_LDOMS_ROLE_SERVICE

See v12n_domain_roles()

V12N_PROP_LDOMS_UUID

See v12n_domain_uuid()

The v12n_list_envs(), v12n_list_env_props (), and v12n_get_prop_name() functions will fail if:

ENOMEM

Insufficient memory to complete the operation.

ENOENT

The specified value does not exist.

The v12n_copy_env() function will fail if:

ENOMEM

Insufficient memory to complete the operation.

The v12n_domain_roles() function fails with EPERM when the calling process has an ID other than the privileged user.

The v12n_domain_name() function will fail if:

EPERM

The calling process has an ID other than the privileged user.

ENOTSUP

Virtualization is not supported or enabled on this domain.

EFAULT

buf points to an illegal address.

ENOENT

The sun4v machine description is inaccessible or has no uuid node.

The v12n_domain_uuid() function will fail if:

EPERM

The calling process has an ID other than the privileged user.

ENOTSUP

Virtualization is not supported or enabled on this domain.

EFAULT

buf points to an illegal address.

ENOENT

The sun4v machine description is inaccessible or has no uuid node.

The v12n_ctrl_domain() function will fail if:

EPERM

The calling process has an ID other than the privileged user.

ENOTSUP

Virtualization is not supported or enabled on this domain.

EFAULT

buf points to an illegal address.

ETIME

The domain service on the control domain did not respond within the timeout value.

The v12n_chassis_serialno() function will fail if:

EPERM

The calling process has an ID other than the privileged user.

ENOTSUP

Virtualization is not supported or enabled on this domain.

EFAULT

buf points to an illegal address.

ETIME

The domain service on the control domain did not respond within the timeout value.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe

See Also

virtinfo(1M) , libuuid (3LIB), libv12n(3LIB) , attributes (5)