path: root/usr/src/man/man2/sysinfo.2

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SYSINFO 2 "Apr 27, 2020"
.SH NAME
sysinfo \- get and set system information strings
.SH SYNOPSIS
.LP
.nf
#include <sys/systeminfo.h>

\fBint\fR \fBsysinfo\fR(\fBint\fR \fIcommand\fR, \fBchar *\fR\fIbuf\fR, \fBlong\fR \fIcount\fR);
.fi

.SH DESCRIPTION
.LP
The \fBsysinfo()\fR function copies information relating to the operating
system on which the process is executing into the buffer pointed to by
\fIbuf\fR. It can also set certain information where appropriate commands are
available. The \fIcount\fR parameter indicates the size of the buffer.
.sp
.LP
The POSIX P1003.1 interface (see \fBstandards\fR(7)) \fBsysconf\fR(3C) provides
a similar class of configuration information, but returns an integer rather
than a string.
.sp
.LP
The values for \fIcommand\fR are as follows:
.sp
.ne 2
.na
\fB\fBSI_SYSNAME\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR the string that would be returned
by \fBuname\fR(2) in the \fIsysname\fR field. This is the name of the
implementation of the operating system, for example, \fBSunOS\fR or \fBUTS\fR.
.RE

.sp
.ne 2
.na
\fB\fBSI_HOSTNAME\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string that names the present
host machine. This is the string that would be returned by \fBuname()\fR in the
\fInodename\fR field. This hostname or nodename is often the name the machine is
known by locally. The \fIhostname\fR is the name of this machine as a node in
some network. Different networks might have different names for the node, but
presenting the nodename to the appropriate network directory or name-to-address
mapping service should produce a transport end point address. The name might
not be fully qualified. Internet host names can be up to \fB256\fR bytes in
length (plus the terminating null).
.RE

.sp
.ne 2
.na
\fB\fBSI_SET_HOSTNAME\fR\fR
.ad
.sp .6
.RS 4n
Copy the null-terminated contents of the array pointed to by \fIbuf\fR into the
string maintained by the kernel whose value will be returned by succeeding
calls to \fBsysinfo()\fR with the command \fBSI_HOSTNAME\fR. This command
requires that {\fBPRIV_SYS_ADMIN\fR} is asserted in the effective set of the
calling process.
.RE

.sp
.ne 2
.na
\fB\fBSI_RELEASE\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR the string that would be returned
by \fBuname\fR(2) in the \fIrelease\fR field. Typical values might be \fB5.2\fR
or \fB4.1\fR.
.RE

.sp
.ne 2
.na
\fB\fBSI_VERSION\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR the string that would be returned
by \fBuname\fR(2) in the \fIversion\fR field. The syntax and semantics of this
string are defined by the system provider.
.RE

.sp
.ne 2
.na
\fB\fBSI_MACHINE\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR the string that would be returned
by \fBuname\fR(2) in the \fImachine\fR field, for example, \fBsun4u\fR.
.RE

.sp
.ne 2
.na
\fB\fBSI_ARCHITECTURE\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string describing the basic
instruction set architecture of the current system, for example, \fBsparc\fR,
\fBmc68030\fR, \fBm32100\fR, or \fBi386\fR. These names might not match
predefined names in the C language compilation system.
.RE

.sp
.ne 2
.na
\fB\fBSI_ARCHITECTURE_64\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string describing the 64-bit
instruction set architecture of the current system, for example, \fBsparcv9\fR
or \fBamd64\fR.  These names might not match predefined names in the C language
compilation system.  This subcode is not recognized on systems that do not
allow a 64-bit application to run.
.RE

.sp
.ne 2
.na
\fB\fBSI_ARCHITECTURE_32\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string describing the 32-bit
instruction set architecture of the current system, for example, \fBsparc\fR or
\fBi386\fR.  These names might not match predefined names in the C language
compilation system.
.RE

.sp
.ne 2
.na
\fB\fBSI_ARCHITECTURE_K\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string describing the kernel
instruction set architecture of the current system for example \fBsparcv9\fR or
\fBi386\fR.  These names might not match predefined names in the C language
compilation system.
.RE

.sp
.ne 2
.na
\fB\fBSI_ARCHITECTURE_NATIVE\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string describing the native
instruction set architecture of the current system, for example \fBsparcv9\fR
or \fBi386\fR.  These names might not match predefined names in the C language
compilation system.
.RE

.sp
.ne 2
.na
\fB\fBSI_ADDRESS_WIDTH\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string describing the number
of bits in the address space of the native instruction set; e.g., \fB32\fR
or \fB64\fR.
.RE

.sp
.ne 2
.na
\fB\fBSI_ISALIST\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR the names of the variant
instruction set architectures executable on the current system.
.sp
The names are space-separated and are ordered in the sense of best performance.
That is, earlier-named instruction sets might contain more instructions than
later-named instruction sets; a program that is compiled for an earlier-named
instruction set will most likely run faster on this machine than the same
program compiled for a later-named instruction set.
.sp
Programs compiled for an instruction set that does not appear in the list will
most likely experience performance degradation or not run at all on this
machine.
.sp
The instruction set names known to the system are listed in \fBisalist\fR(7);
these names might not match predefined names or compiler options in the C
language compilation system.
.sp
This command is obsolete and might be removed in a future release. See
\fBgetisax\fR(2) and the \fILinker and Libraries Guide\fR for a better way to
handle instruction set extensions.
.RE

.sp
.ne 2
.na
\fB\fBSI_PLATFORM\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string describing the specific
model of the hardware platform, for example, \fBSUNW,Sun-Blade-1500\fR,
\fBSUNW,Sun-Fire-T200\fR, or \fBi86pc\fR.
.RE

.sp
.ne 2
.na
\fB\fBSI_HW_PROVIDER\fR\fR
.ad
.sp .6
.RS 4n
Copies the name of the hardware manufacturer into the array pointed to by
\fIbuf\fR.
.RE

.sp
.ne 2
.na
\fB\fBSI_HW_SERIAL\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR a string which is the ASCII
representation of the hardware-specific serial number of the physical machine
on which the function is executed. This might be implemented in Read-Only
Memory, using software constants set when building the operating system, or by
other means, and might contain non-numeric characters. If the function is
executed within a non-global zone that emulates a host identifier, then the
ASCII representation of the zone's host identifier is copied into the array
pointed to by \fIbuf\fR. It is anticipated that manufacturers will not issue
the same "serial number" to more than one physical machine. The pair of strings
returned by \fBSI_HW_PROVIDER\fR and \fBSI_HW_SERIAL\fR is not guaranteed to be
unique across all vendor's SVR4 implementations and could change over the
lifetime of a given system.
.RE

.sp
.ne 2
.na
\fB\fBSI_SRPC_DOMAIN\fR\fR
.ad
.sp .6
.RS 4n
Copies the Secure Remote Procedure Call domain name into the array pointed to
by \fIbuf\fR.
.RE

.sp
.ne 2
.na
\fB\fBSI_SET_SRPC_DOMAIN\fR\fR
.ad
.sp .6
.RS 4n
Set the string to be returned by \fBsysinfo()\fR with the \fBSI_SRPC_DOMAIN\fR
command to the value contained in the array pointed to by \fIbuf\fR. This
command requires that {\fBPRIV_SYS_ADMIN\fR} is asserted in the effective set
of the calling process.
.RE

.sp
.ne 2
.na
\fB\fBSI_DHCP_CACHE\fR\fR
.ad
.sp .6
.RS 4n
Copy into the array pointed to by \fIbuf\fR an ASCII string consisting of the
ASCII hexadecimal encoding of the name of the interface configured by
\fBboot\fR(8) followed by the DHCPACK reply from the server. This command is
intended for use only by the \fBdhcpagent\fR(8) DHCP client daemon for the
purpose of adopting the DHCP maintenance of the interface configured by
\fBboot\fR.
.RE

.SH RETURN VALUES
.LP
Upon successful completion, the value returned indicates the buffer size in
bytes required to hold the complete value and the terminating null character.
If this value is no greater than the value passed in \fIcount\fR, the entire
string was copied. If this value is greater than \fIcount\fR, the string copied
into \fIbuf\fR has been truncated to  \fIcount\fR\(mi1 bytes plus a terminating
null character.
.sp
.LP
Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.LP
The \fBsysinfo()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The \fIbuf\fR argument does not point to a valid address.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIcount\fR argument for a non-SET command is less than 0 or the data for a
SET command exceeds the limits established by the implementation.
.RE

.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 10n
The {\fBPRIV_SYS_ADMIN\fR} was not asserted in the effective set of the calling
process.
.RE

.SH USAGE
.LP
In many cases there is no corresponding programming interface to set these
values; such strings are typically settable only by the system administrator
modifying entries in the \fB/etc/system\fR directory or the code provided by
the particular OEM reading a serial number or code out of read-only memory, or
hard-coded in the version of the operating system.
.sp
.LP
A good estimation for \fIcount\fR is 257, which is likely to cover all strings
returned by this interface in typical installations.
.SH SEE ALSO
.LP
.BR getisax (2),
.BR uname (2),
.BR gethostid (3C),
.BR gethostname (3C),
.BR sysconf (3C),
.BR isalist (7),
.BR privileges (7),
.BR standards (7),
.BR zones (7),
.BR boot (8),
.BR dhcpagent (8)
.sp
.LP
\fILinker and Libraries Guide\fR