1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH SYSINFO 2 "Sep 7, 2015"
   8 .SH NAME
   9 sysinfo \- get and set system information strings
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/systeminfo.h>
  14 
  15 \fBint\fR \fBsysinfo\fR(\fBint\fR \fIcommand\fR, \fBchar *\fR\fIbuf\fR, \fBlong\fR \fIcount\fR);
  16 .fi
  17 
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBsysinfo()\fR function copies information relating to the operating
  21 system on which the process is executing into the buffer pointed to by
  22 \fIbuf\fR. It can also set certain information where appropriate commands are
  23 available. The \fIcount\fR parameter indicates the size of the buffer.
  24 .sp
  25 .LP
  26 The POSIX P1003.1 interface (see \fBstandards\fR(5)) \fBsysconf\fR(3C) provides
  27 a similar class of configuration information, but returns an integer rather
  28 than a string.
  29 .sp
  30 .LP
  31 The values for \fIcommand\fR are as follows:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fBSI_SYSNAME\fR\fR
  36 .ad
  37 .sp .6
  38 .RS 4n
  39 Copy into the array pointed to by \fIbuf\fR the string that would be returned
  40 by \fBuname\fR(2) in the \fIsysname\fR field. This is the name of the
  41 implementation of the operating system, for example, \fBSunOS\fR or \fBUTS\fR.
  42 .RE
  43 
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBSI_HOSTNAME\fR\fR
  48 .ad
  49 .sp .6
  50 .RS 4n
  51 Copy into the array pointed to by \fIbuf\fR a string that names the present
  52 host machine. This is the string that would be returned by \fBuname()\fR in the
  53 \fInodename\fR field. This hostname or nodename is often the name the machine is
  54 known by locally. The \fIhostname\fR is the name of this machine as a node in
  55 some network. Different networks might have different names for the node, but
  56 presenting the nodename to the appropriate network directory or name-to-address
  57 mapping service should produce a transport end point address. The name might
  58 not be fully qualified. Internet host names can be up to \fB256\fR bytes in
  59 length (plus the terminating null).
  60 .RE
  61 
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBSI_SET_HOSTNAME\fR\fR
  66 .ad
  67 .sp .6
  68 .RS 4n
  69 Copy the null-terminated contents of the array pointed to by \fIbuf\fR into the
  70 string maintained by the kernel whose value will be returned by succeeding
  71 calls to \fBsysinfo()\fR with the command \fBSI_HOSTNAME\fR. This command
  72 requires that {\fBPRIV_SYS_ADMIN\fR} is asserted in the effective set of the
  73 calling process.
  74 .RE
  75 
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBSI_RELEASE\fR\fR
  80 .ad
  81 .sp .6
  82 .RS 4n
  83 Copy into the array pointed to by \fIbuf\fR the string that would be returned
  84 by \fBuname\fR(2) in the \fIrelease\fR field. Typical values might be \fB5.2\fR
  85 or \fB4.1\fR.
  86 .RE
  87 
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBSI_VERSION\fR\fR
  92 .ad
  93 .sp .6
  94 .RS 4n
  95 Copy into the array pointed to by \fIbuf\fR the string that would be returned
  96 by \fBuname\fR(2) in the \fIversion\fR field. The syntax and semantics of this
  97 string are defined by the system provider.
  98 .RE
  99 
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBSI_MACHINE\fR\fR
 104 .ad
 105 .sp .6
 106 .RS 4n
 107 Copy into the array pointed to by \fIbuf\fR the string that would be returned
 108 by \fBuname\fR(2) in the \fImachine\fR field, for example, \fBsun4u\fR.
 109 .RE
 110 
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBSI_ARCHITECTURE\fR\fR
 115 .ad
 116 .sp .6
 117 .RS 4n
 118 Copy into the array pointed to by \fIbuf\fR a string describing the basic
 119 instruction set architecture of the current system, for example, \fBsparc\fR,
 120 \fBmc68030\fR, \fBm32100\fR, or \fBi386\fR. These names might not match
 121 predefined names in the C language compilation system.
 122 .RE
 123 
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBSI_ARCHITECTURE_64\fR\fR
 128 .ad
 129 .sp .6
 130 .RS 4n
 131 Copy into the array pointed to by \fIbuf\fR a string describing the 64-bit
 132 instruction set architecture of the current system, for example, \fBsparcv9\fR
 133 or \fBamd64\fR.  These names might not match predefined names in the C language
 134 compilation system.  This subcode is not recognized on systems that do not
 135 allow a 64-bit application to run.
 136 .RE
 137 
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBSI_ARCHITECTURE_32\fR\fR
 142 .ad
 143 .sp .6
 144 .RS 4n
 145 Copy into the array pointed to by \fIbuf\fR a string describing the 32-bit
 146 instruction set architecture of the current system, for example, \fBsparc\fR or
 147 \fBi386\fR.  These names might not match predefined names in the C language
 148 compilation system.
 149 .RE
 150 
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBSI_ARCHITECTURE_K\fR\fR
 155 .ad
 156 .sp .6
 157 .RS 4n
 158 Copy into the array pointed to by \fIbuf\fR a string describing the kernel
 159 instruction set architecture of the current system for example \fBsparcv9\fR or
 160 \fBi386\fR.  These names might not match predefined names in the C language
 161 compilation system.
 162 .RE
 163 
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBSI_ARCHITECTURE_NATIVE\fR\fR
 168 .ad
 169 .sp .6
 170 .RS 4n
 171 Copy into the array pointed to by \fIbuf\fR a string describing the native
 172 instruction set architecture of the current system, for example \fBsparcv9\fR
 173 or \fBi386\fR.  These names might not match predefined names in the C language
 174 compilation system.
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBSI_ISALIST\fR\fR
 181 .ad
 182 .sp .6
 183 .RS 4n
 184 Copy into the array pointed to by \fIbuf\fR the names of the variant
 185 instruction set architectures executable on the current system.
 186 .sp
 187 The names are space-separated and are ordered in the sense of best performance.
 188 That is, earlier-named instruction sets might contain more instructions than
 189 later-named instruction sets; a program that is compiled for an earlier-named
 190 instruction set will most likely run faster on this machine than the same
 191 program compiled for a later-named instruction set.
 192 .sp
 193 Programs compiled for an instruction set that does not appear in the list will
 194 most likely experience performance degradation or not run at all on this
 195 machine.
 196 .sp
 197 The instruction set names known to the system are listed in \fBisalist\fR(5);
 198 these names might not match predefined names or compiler options in the C
 199 language compilation system.
 200 .sp
 201 This command is obsolete and might be removed in a future release. See
 202 \fBgetisax\fR(2) and the \fILinker and Libraries Guide\fR for a better way to
 203 handle instruction set extensions.
 204 .RE
 205 
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBSI_PLATFORM\fR\fR
 210 .ad
 211 .sp .6
 212 .RS 4n
 213 Copy into the array pointed to by \fIbuf\fR a string describing the specific
 214 model of the hardware platform, for example, \fBSUNW,Sun-Blade-1500\fR,
 215 \fBSUNW,Sun-Fire-T200\fR, or \fBi86pc\fR.
 216 .RE
 217 
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBSI_HW_PROVIDER\fR\fR
 222 .ad
 223 .sp .6
 224 .RS 4n
 225 Copies the name of the hardware manufacturer into the array pointed to by
 226 \fIbuf\fR.
 227 .RE
 228 
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fBSI_HW_SERIAL\fR\fR
 233 .ad
 234 .sp .6
 235 .RS 4n
 236 Copy into the array pointed to by \fIbuf\fR a string which is the ASCII
 237 representation of the hardware-specific serial number of the physical machine
 238 on which the function is executed. This might be implemented in Read-Only
 239 Memory, using software constants set when building the operating system, or by
 240 other means, and might contain non-numeric characters. If the function is
 241 executed within a non-global zone that emulates a host identifier, then the
 242 ASCII representation of the zone's host identifier is copied into the array
 243 pointed to by \fIbuf\fR. It is anticipated that manufacturers will not issue
 244 the same "serial number" to more than one physical machine. The pair of strings
 245 returned by \fBSI_HW_PROVIDER\fR and \fBSI_HW_SERIAL\fR is not guaranteed to be
 246 unique across all vendor's SVR4 implementations and could change over the
 247 lifetime of a given system.
 248 .RE
 249 
 250 .sp
 251 .ne 2
 252 .na
 253 \fB\fBSI_SRPC_DOMAIN\fR\fR
 254 .ad
 255 .sp .6
 256 .RS 4n
 257 Copies the Secure Remote Procedure Call domain name into the array pointed to
 258 by \fIbuf\fR.
 259 .RE
 260 
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fBSI_SET_SRPC_DOMAIN\fR\fR
 265 .ad
 266 .sp .6
 267 .RS 4n
 268 Set the string to be returned by \fBsysinfo()\fR with the \fBSI_SRPC_DOMAIN\fR
 269 command to the value contained in the array pointed to by \fIbuf\fR. This
 270 command requires that {\fBPRIV_SYS_ADMIN\fR} is asserted in the effective set
 271 of the calling process.
 272 .RE
 273 
 274 .sp
 275 .ne 2
 276 .na
 277 \fB\fBSI_DHCP_CACHE\fR\fR
 278 .ad
 279 .sp .6
 280 .RS 4n
 281 Copy into the array pointed to by \fIbuf\fR an ASCII string consisting of the
 282 ASCII hexadecimal encoding of the name of the interface configured by
 283 \fBboot\fR(1M) followed by the DHCPACK reply from the server. This command is
 284 intended for use only by the \fBdhcpagent\fR(1M) DHCP client daemon for the
 285 purpose of adopting the DHCP maintenance of the interface configured by
 286 \fBboot\fR.
 287 .RE
 288 
 289 .SH RETURN VALUES
 290 .LP
 291 Upon successful completion, the value returned indicates the buffer size in
 292 bytes required to hold the complete value and the terminating null character.
 293 If this value is no greater than the value passed in \fIcount\fR, the entire
 294 string was copied. If this value is greater than \fIcount\fR, the string copied
 295 into \fIbuf\fR has been truncated to  \fIcount\fR\(mi1 bytes plus a terminating
 296 null character.
 297 .sp
 298 .LP
 299 Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate the error.
 300 .SH ERRORS
 301 .LP
 302 The \fBsysinfo()\fR function will fail if:
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fBEFAULT\fR\fR
 307 .ad
 308 .RS 10n
 309 The \fIbuf\fR argument does not point to a valid address.
 310 .RE
 311 
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBEINVAL\fR\fR
 316 .ad
 317 .RS 10n
 318 The \fIcount\fR argument for a non-SET command is less than 0 or the data for a
 319 SET command exceeds the limits established by the implementation.
 320 .RE
 321 
 322 .sp
 323 .ne 2
 324 .na
 325 \fB\fBEPERM\fR\fR
 326 .ad
 327 .RS 10n
 328 The {\fBPRIV_SYS_ADMIN\fR} was not asserted in the effective set of the calling
 329 process.
 330 .RE
 331 
 332 .SH USAGE
 333 .LP
 334 In many cases there is no corresponding programming interface to set these
 335 values; such strings are typically settable only by the system administrator
 336 modifying entries in the \fB/etc/system\fR directory or the code provided by
 337 the particular OEM reading a serial number or code out of read-only memory, or
 338 hard-coded in the version of the operating system.
 339 .sp
 340 .LP
 341 A good estimation for \fIcount\fR is 257, which is likely to cover all strings
 342 returned by this interface in typical installations.
 343 .SH SEE ALSO
 344 .LP
 345 \fBboot\fR(1M), \fBdhcpagent\fR(1M), \fBgetisax\fR(2), \fBuname\fR(2),
 346 \fBgethostid\fR(3C), \fBgethostname\fR(3C), \fBsysconf\fR(3C),
 347 \fBisalist\fR(5), \fBprivileges\fR(5), \fBstandards\fR(5), \fBzones\fR(5)
 348 .sp
 349 .LP
 350 \fILinker and Libraries Guide\fR