'\" te .\" Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. .TH v12n 3EXT "5 Nov 2013" "SunOS 5.11" "Extended Library Functions" .SH 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 .SH SYNOPSIS .LP .nf cc [ \fIflag\fR... ] \fIfile\fR... -lv12n [ \fIlibrary\fR... ] #include .fi .LP .nf v12n_env_t * v12n_get_current_env(void); .fi .LP .nf v12n_env_t * v12n_get_parent_env(void); .fi .LP .nf char * v12n_get_env_prop(v12n_env_t *\fIenvironment\fR, v12n_prop_t property); .fi .LP .nf v12n_env_t ** v12n_list_supported_envs(void); .fi .LP .nf v12n_env_t ** v12n_list_envs(void); .fi .LP .nf v12n_env_t ** v12n_list_env_props(v12n_env_t *\fIenvironment\fR); .fi .LP .nf const char *v12n_get_prop_name(v12n_prop_t property); .fi .LP .nf void v12n_free_env(v12n_env_t *\fIenvironment\fR) .fi .LP .nf v12n_env_t * v12n_copy_env(v12n_env_t *\fIenvironment\fR) .fi .SH DESCRIPTION .sp .LP \fBv12n_env_t\fR is an opaque type. The supported functions, return values, and errors are described below: .sp .ne 2 .mk .na \fB\fBv12n_get_current_env()\fR\fR .ad .RS 30n .rt Returns the current environment. See below for the list of possible environment names. .RE .sp .ne 2 .mk .na \fB\fBv12n_get_parent_env()\fR\fR .ad .RS 30n .rt 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. .RE .sp .ne 2 .mk .na \fB\fBv12n_get_env_prop()\fR\fR .ad .RS 30n .rt Returns a string representation of a requested property for a given environment. The returned string must be freed by the caller. .RE .sp .ne 2 .mk .na \fB\fBv12n_list_supported_envs()\fR\fR .ad .RS 30n .rt 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. .RE .sp .ne 2 .mk .na \fB\fBv12n_list_envs()\fR\fR .ad .RS 30n .rt 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. .RE .sp .ne 2 .mk .na \fB\fBv12n_list_env_props()\fR\fR .ad .RS 30n .rt 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. .RE .sp .ne 2 .mk .na \fB\fBv12n_get_prop_name()\fR\fR .ad .RS 30n .rt Returns a string representation of a virtual environment property. .RE .sp .ne 2 .mk .na \fB\fBv12n_free_env()\fR\fR .ad .RS 30n .rt Frees the storage associated with an \fBv12n_env_t\fR. .RE .sp .ne 2 .mk .na \fB\fBv12n_copy_env()\fR\fR .ad .RS 30n .rt Copies the supplied \fBv12n_env_t\fR. A new \fBv12n_env_t\fR is returned. .RE .SH ENVIRONMENTS .sp .LP \fBlibv12n\fR knows about the following environments. As some are SPARC or x86 specific, they may not be available on both platforms. .sp .sp .TS tab(); cw(1.83i) cw(1.83i) cw(1.83i) lw(1.83i) lw(1.83i) lw(1.83i) . TypeNamePlatform _ Unknown\fBunknown\fRBoth Kernel-based Virtual Machine\fBkvm\fRx86 Logical Domains\fBlogical-domain\fRSPARC Non-Global Zone\fBnon-global-zone\fRBoth Kernel Zone\fBkernel-zone\fRBoth VMware\fBvmware\fRx86 VirtualBox\fBvirtualbox\fRx86 Xen\fBxen\fRx86 .TE .SH PROPERTIES .sp .LP \fBlibv12n\fR knows about the following properties. Properties depend both on the class as well as the name of the environment. .sp .sp .TS tab(); cw(1.83i) cw(1.83i) cw(1.83i) lw(1.83i) lw(1.83i) lw(1.83i) . TypeClassName _ V12N_PROP_NAME(all)\fBname\fR V12N_PROP_CLASS(all)\fBclass\fR V12N_PROP_LDOMS_CHASSIS\fBcurrent\fR\fBchassis-serial-number\fR V12N_PROP_LDOMS_CONTROL_NAME\fBcurrent\fR\fBcontrol-name\fR V12N_PROP_LDOMS_NAME\fBcurrent\fR\fBdomain-name\fR V12N_PROP_LDOMS_ROLE_CONTROL\fBcurrent\fR\fBcontrol-role\fR V12N_PROP_LDOMS_ROLE_IO\fBcurrent\fR\fBio-role\fR V12N_PROP_LDOMS_ROLE_ROOT\fBcurrent\fR\fBroot-role\fR V12N_PROP_LDOMS_ROLE_SERVICE\fBcurrent\fR\fBservice-role\fR V12N_PROP_LDOMS_UUID\fBcurrent\fR\fBuuid\fR .TE .SH LEGACY .LP .nf int \fBv12n_capabilities()\fR; .fi .LP .nf int \fBv12n_domain_roles()\fR; .fi .LP .nf int v12n_domain_uuid(uuid_t uuid); .fi .LP .nf size_t v12n_domain_name(char *\fIbuf\fR, size_t \fIbuflen\fR); .fi .LP .nf size_t v12n_ctrl_domain(char *\fIbuf\fR, size_t \fIbuflen\fR); .fi .LP .nf size_t v12n_chassis_serialno(char *\fIbuf\fR, size_t \fIbuflen\fR); .fi .sp .LP The \fBv12n_capabilities()\fR function returns the virtualization capabilities mask of the current domain. The virtualization capabilities bit mask consists of the following values: .sp .sp .TS tab(); cw(2.28i) cw(3.22i) lw(2.28i) lw(3.22i) . ValueDescription _ V12N_CAP_SUPPORTEDT{ Virtualization is supported on this domain. T} V12N_CAP_ENABLEDT{ Virtualization is enabled on this domain. T} V12N_CAP_IMPL_LDOMST{ Logical Domains is the supported virtualization implementation. T} .TE .sp .LP The \fBv12n_domain_roles()\fR function returns the virtualization domain role mask. The virtualization domain role mask consists of the following values: .sp .sp .TS tab(); cw(2.28i) cw(3.22i) lw(2.28i) lw(3.22i) . ValueDescription _ V12N_ROLE_CONTROLT{ 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. T} V12N_ROLE_IOCurrent domain is an I/O domain. V12N_ROLE_SERVICECurrent domain is a service domain. V12N_ROLE_ROOTCurrent domain is a root I/O domain. .TE .sp .LP The \fBv12n_domain_uuid()\fR function stores the universally unique identifier (UUID) for the current virtualization domain in the \fBuuid\fR argument. See the \fBlibuuid\fR(3LIB) manual page. .sp .LP The \fBv12n_domain_name()\fR function stores the name of the current virtualization domain in the location specified by \fIbuf\fR. \fIbuflen\fR specifies the size in bytes of the buffer. If the buffer is too small to hold the complete null-terminated name, the first \fIbuflen\fR bytes of the name are stored in the buffer. A buffer of size \fBV12N_NAME_MAX\fR is sufficient to hold any domain name. If \fIbuf\fR is NULL or \fIbuflen\fR is 0, the name is not copied into the buffer. .sp .LP The \fBv12n_ctrl_domain()\fR function stores the control domain or dom0 network node name of the current domain in the location specified by \fIbuf\fR. 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. \fIbuflen\fR specifies the size in bytes of the buffer. If the buffer is too small to hold the complete null-terminated name, the first \fIbuflen\fR bytes of the name are stored in the buffer. A buffer of size \fBV12N_NAME_MAX\fR is sufficient to hold the control domain node name string. If \fIbuf\fR is NULL or \fIbuflen\fR is 0, the name is not copied into the buffer. .sp .LP The \fBv12n_chassis_serialno()\fR function stores the chassis serial number of the platform on which the current domain is running in the location specified by \fIbuf\fR. 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. \fIbuflen\fR specifies the size in bytes of the buffer. If the buffer is too small to hold the complete null-terminated name, the first \fIbuflen\fR bytes of the name are stored in the buffer. A buffer of size \fBV12N_NAME_MAX\fR is sufficient to hold any chassis serial number string. If \fIbuf\fR is NULL or \fIbuflen\fR is 0, the name is not copied into the buffer. .SH RETURN VALUES .sp .LP On successful completion, the \fBv12n_get_current_env()\fR, \fBv12n_get_parent_env()\fR and \fBv12n_copy_env()\fR functions return an opaque pointer to a \fBv12n_env_t\fR representing an environment. Otherwise, the \fBv12n_get_current_env()\fR function returns NULL and sets \fBerrno\fR to indicate the error. .sp .LP On successful completion, the \fBv12n_get_env_prop()\fR returns a string holding the property value. the \fBv12n_get_current_env()\fR function returns NULL and sets \fBerrno\fR to indicate the error. .sp .LP On successful completion, the \fBv12n_list_supported_envs()\fR, \fBv12n_list_envs()\fR, and \fBv12n_list_env_props()\fR functions return an array. Otherwise, these functions return NULL and sets \fBerrno\fR to indicate the error. .sp .LP On successful completion, the \fBv12n_capabilties()\fR and \fBv12n_domain_roles()\fR functions return a non-negative bit mask. Otherwise, the \fBv12n_domain_roles()\fR function returns -1 and sets \fBerrno\fR to indicate the error. .sp .LP On successful completion, the \fBv12n_domain_uuid()\fR function returns 0. Otherwise, the \fBv12n_domain_uuid()\fR function returns -1 and sets \fBerrno\fR to indicate the error. .sp .LP On successful completion, the \fBv12n_domain_name()\fR, \fBv12n_ctrl_domain()\fR, and \fBv12n_chassis_serialno()\fR functions return the buffer size required to hold the full non-terminated string. Otherwise, these functions return -1 and set \fBerrno\fR to indicate the error. .SH ERRORS .sp .LP The \fBv12n_get_current_env()\fR and \fBv12n_get_parent_env()\fR functions fail if: .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt Insufficient memory to complete the operation. .RE .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 10n .rt The calling process has insufficient privilege for accessing device configuration data (x86 only). .RE .sp .ne 2 .mk .na \fB\fBENXIO\fR\fR .ad .RS 10n .rt The \fBdevinfo\fR(7D) driver is not installed properly (x86 only). .RE .sp .LP The \fBv12n_list_supported_envs()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt Insufficient memory to complete the operation. .RE .sp .LP The \fBv12n_get_env_prop()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt The specified environment or property does not exist. .RE .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt Insufficient memory to complete the operation. .RE .sp .LP For the logical domain properties: .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_CHASSIS\fR\fR .ad .sp .6 .RS 4n See \fBv12n_chassis_serialno()\fR .RE .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_CONTROL_NAME\fR\fR .ad .sp .6 .RS 4n See \fBv12n_ctrl_domain()\fR .RE .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_NAME\fR\fR .ad .sp .6 .RS 4n See \fBv12n_domain_name()\fR .RE .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_ROLE_CONTROL\fR\fR .ad .sp .6 .RS 4n See \fBv12n_domain_roles()\fR .RE .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_ROLE_IO\fR\fR .ad .sp .6 .RS 4n See \fBv12n_domain_roles()\fR .RE .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_ROLE_ROOT\fR\fR .ad .sp .6 .RS 4n See \fBv12n_domain_roles()\fR .RE .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_ROLE_SERVICE\fR\fR .ad .sp .6 .RS 4n See \fBv12n_domain_roles()\fR .RE .sp .ne 2 .mk .na \fB\fBV12N_PROP_LDOMS_UUID\fR\fR .ad .sp .6 .RS 4n See \fBv12n_domain_uuid()\fR .RE .sp .LP The \fBv12n_list_envs()\fR, \fBv12n_list_env_props()\fR, and \fBv12n_get_prop_name()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt Insufficient memory to complete the operation. .RE .sp .ne 2 .mk .na \fB\fBENOENT\fR\fR .ad .RS 10n .rt The specified value does not exist. .RE .sp .LP The \fBv12n_copy_env()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt Insufficient memory to complete the operation. .RE .sp .LP The \fBv12n_domain_roles()\fR function fails with \fBEPERM\fR when the calling process has an ID other than the privileged user. .sp .LP The \fBv12n_domain_name()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 11n .rt The calling process has an ID other than the privileged user. .RE .sp .ne 2 .mk .na \fB\fBENOTSUP\fR\fR .ad .RS 11n .rt Virtualization is not supported or enabled on this domain. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 11n .rt \fIbuf\fR points to an illegal address. .RE .sp .ne 2 .mk .na \fB\fBENOENT\fR\fR .ad .RS 11n .rt The \fBsun4v\fR machine description is inaccessible or has no \fBuuid\fR node. .RE .sp .LP The \fBv12n_domain_uuid()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 11n .rt The calling process has an ID other than the privileged user. .RE .sp .ne 2 .mk .na \fB\fBENOTSUP\fR\fR .ad .RS 11n .rt Virtualization is not supported or enabled on this domain. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 11n .rt \fBbuf\fR points to an illegal address. .RE .sp .ne 2 .mk .na \fB\fBENOENT\fR\fR .ad .RS 11n .rt The sun4v machine description is inaccessible or has no \fBuuid\fR node. .RE .sp .LP The \fBv12n_ctrl_domain()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 11n .rt The calling process has an ID other than the privileged user. .RE .sp .ne 2 .mk .na \fB\fBENOTSUP\fR\fR .ad .RS 11n .rt Virtualization is not supported or enabled on this domain. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 11n .rt \fIbuf\fR points to an illegal address. .RE .sp .ne 2 .mk .na \fB\fBETIME\fR\fR .ad .RS 11n .rt The domain service on the control domain did not respond within the timeout value. .RE .sp .LP The \fBv12n_chassis_serialno()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 11n .rt The calling process has an ID other than the privileged user. .RE .sp .ne 2 .mk .na \fB\fBENOTSUP\fR\fR .ad .RS 11n .rt Virtualization is not supported or enabled on this domain. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 11n .rt \fIbuf\fR points to an illegal address. .RE .sp .ne 2 .mk .na \fB\fBETIME\fR\fR .ad .RS 11n .rt The domain service on the control domain did not respond within the timeout value. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe .TE .SH SEE ALSO .sp .LP \fBvirtinfo\fR(1M), \fBlibuuid\fR(3LIB), \fBlibv12n\fR(3LIB), \fBattributes\fR(5)