VirtualBox

source: vbox/trunk/include/iprt/system.h@ 68716

Last change on this file since 68716 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.0 KB
Line 
1/** @file
2 * IPRT - System Information.
3 */
4
5/*
6 * Copyright (C) 2006-2016 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_system_h
27#define ___iprt_system_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_system RTSystem - System Information
36 * @ingroup grp_rt
37 * @{
38 */
39
40/**
41 * Info level for RTSystemGetOSInfo().
42 */
43typedef enum RTSYSOSINFO
44{
45 RTSYSOSINFO_INVALID = 0, /**< The usual invalid entry. */
46 RTSYSOSINFO_PRODUCT, /**< OS product name. (uname -o) */
47 RTSYSOSINFO_RELEASE, /**< OS release. (uname -r) */
48 RTSYSOSINFO_VERSION, /**< OS version, optional. (uname -v) */
49 RTSYSOSINFO_SERVICE_PACK, /**< Service/fix pack level, optional. */
50 RTSYSOSINFO_END /**< End of the valid info levels. */
51} RTSYSOSINFO;
52
53
54/**
55 * Queries information about the OS.
56 *
57 * @returns IPRT status code.
58 * @retval VINF_SUCCESS on success.
59 * @retval VERR_INVALID_PARAMETER if enmInfo is invalid.
60 * @retval VERR_INVALID_POINTER if pszInfoStr is invalid.
61 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will
62 * contain the chopped off result in this case, provided cchInfo isn't 0.
63 * @retval VERR_NOT_SUPPORTED if the info level isn't implemented. The buffer will
64 * contain an empty string.
65 *
66 * @param enmInfo The OS info level.
67 * @param pszInfo Where to store the result.
68 * @param cchInfo The size of the output buffer.
69 */
70RTDECL(int) RTSystemQueryOSInfo(RTSYSOSINFO enmInfo, char *pszInfo, size_t cchInfo);
71
72/**
73 * Queries the total amount of RAM in the system.
74 *
75 * This figure does not given any information about how much memory is
76 * currently available. Use RTSystemQueryAvailableRam instead.
77 *
78 * @returns IPRT status code.
79 * @retval VINF_SUCCESS and *pcb on sucess.
80 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
81 * caller.
82 *
83 * @param pcb Where to store the result (in bytes).
84 */
85RTDECL(int) RTSystemQueryTotalRam(uint64_t *pcb);
86
87/**
88 * Queries the total amount of RAM accessible to the system.
89 *
90 * This figure should not include memory that is installed but not used,
91 * nor memory that will be slow to bring online. The definition of 'slow'
92 * here is slower than swapping out a MB of pages to disk.
93 *
94 * @returns IPRT status code.
95 * @retval VINF_SUCCESS and *pcb on success.
96 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
97 * caller.
98 *
99 * @param pcb Where to store the result (in bytes).
100 */
101RTDECL(int) RTSystemQueryAvailableRam(uint64_t *pcb);
102
103/**
104 * Queries the amount of RAM that is currently locked down or in some other
105 * way made impossible to virtualize within reasonably short time.
106 *
107 * The purposes of this API is, when combined with RTSystemQueryTotalRam, to
108 * be able to determine an absolute max limit for how much fixed memory it is
109 * (theoretically) possible to allocate (or lock down).
110 *
111 * The kind memory covered by this function includes:
112 * - locked (wired) memory - like for instance RTR0MemObjLockUser
113 * and RTR0MemObjLockKernel makes,
114 * - kernel pools and heaps - like for instance the ring-0 variant
115 * of RTMemAlloc taps into,
116 * - fixed (not pageable) kernel allocations - like for instance
117 * all the RTR0MemObjAlloc* functions makes,
118 * - any similar memory that isn't easily swapped out, discarded,
119 * or flushed to disk.
120 *
121 * This works against the value returned by RTSystemQueryTotalRam, and
122 * the value reported by this function can never be larger than what a
123 * call to RTSystemQueryTotalRam returns.
124 *
125 * The short time term here is relative to swapping to disk like in
126 * RTSystemQueryTotalRam. This could mean that (part of) the dirty buffers
127 * in the dynamic I/O cache could be included in the total. If the dynamic
128 * I/O cache isn't likely to either flush buffers when the load increases
129 * and put them back into normal circulation, they should be included in
130 * the memory accounted for here.
131 *
132 * @retval VINF_SUCCESS and *pcb on success.
133 * @retval VERR_NOT_SUPPORTED if the information isn't available on the
134 * system in general. The caller must handle this scenario.
135 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
136 * caller.
137 *
138 * @param pcb Where to store the result (in bytes).
139 *
140 * @remarks This function could've been inverted and called
141 * RTSystemQueryAvailableRam, but that might give impression that
142 * it would be possible to allocate the amount of memory it
143 * indicates for a single purpose, something which would be very
144 * improbable on most systems.
145 *
146 * @remarks We might have to add another output parameter to this function
147 * that indicates if some of the memory kinds listed above cannot
148 * be accounted for on the system and therefore is not include in
149 * the returned amount.
150 */
151RTDECL(int) RTSystemQueryUnavailableRam(uint64_t *pcb);
152
153
154/**
155 * The DMI strings.
156 */
157typedef enum RTSYSDMISTR
158{
159 /** Invalid zero entry. */
160 RTSYSDMISTR_INVALID = 0,
161 /** The product name. */
162 RTSYSDMISTR_PRODUCT_NAME,
163 /** The product version. */
164 RTSYSDMISTR_PRODUCT_VERSION,
165 /** The product UUID. */
166 RTSYSDMISTR_PRODUCT_UUID,
167 /** The product serial. */
168 RTSYSDMISTR_PRODUCT_SERIAL,
169 /** The system manufacturer. */
170 RTSYSDMISTR_MANUFACTURER,
171 /** The end of the valid strings. */
172 RTSYSDMISTR_END,
173 /** The usual 32-bit hack. */
174 RTSYSDMISTR_32_BIT_HACK = 0x7fffffff
175} RTSYSDMISTR;
176
177/**
178 * Queries a DMI string.
179 *
180 * @returns IPRT status code.
181 * @retval VINF_SUCCESS on success.
182 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will
183 * contain the chopped off result in this case, provided cbBuf isn't 0.
184 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
185 * caller.
186 * @retval VERR_NOT_SUPPORTED if the information isn't available on the system
187 * in general. The caller must expect this status code and deal with
188 * it.
189 *
190 * @param enmString Which string to query.
191 * @param pszBuf Where to store the string. This is always
192 * terminated, even on error.
193 * @param cbBuf The buffer size.
194 */
195RTDECL(int) RTSystemQueryDmiString(RTSYSDMISTR enmString, char *pszBuf, size_t cbBuf);
196
197/** @name Flags for RTSystemReboot and RTSystemShutdown.
198 * @{ */
199/** Reboot the system after shutdown. */
200#define RTSYSTEM_SHUTDOWN_REBOOT UINT32_C(0)
201/** Reboot the system after shutdown.
202 * The call may return VINF_SYS_MAY_POWER_OFF if the OS /
203 * hardware combination may power off instead of halting. */
204#define RTSYSTEM_SHUTDOWN_HALT UINT32_C(1)
205/** Power off the system after shutdown.
206 * This may be equvivalent to a RTSYSTEM_SHUTDOWN_HALT on systems where we
207 * cannot figure out whether the hardware/OS implements the actual powering
208 * off. If we can figure out that it's not supported, an
209 * VERR_SYS_CANNOT_POWER_OFF error is raised. */
210#define RTSYSTEM_SHUTDOWN_POWER_OFF UINT32_C(2)
211/** Power off the system after shutdown, or halt it if that's not possible. */
212#define RTSYSTEM_SHUTDOWN_POWER_OFF_HALT UINT32_C(3)
213/** The shutdown action mask. */
214#define RTSYSTEM_SHUTDOWN_ACTION_MASK UINT32_C(3)
215/** Unplanned shutdown/reboot. */
216#define RTSYSTEM_SHUTDOWN_UNPLANNED UINT32_C(0)
217/** Planned shutdown/reboot. */
218#define RTSYSTEM_SHUTDOWN_PLANNED RT_BIT_32(2)
219/** Force the system to shutdown/reboot regardless of objecting application
220 * or other stuff. This flag might not be realized on all systems. */
221#define RTSYSTEM_SHUTDOWN_FORCE RT_BIT_32(3)
222/** Parameter validation mask. */
223#define RTSYSTEM_SHUTDOWN_VALID_MASK UINT32_C(0x0000000f)
224/** @} */
225
226/**
227 * Shuts down the system.
228 *
229 * @returns IPRT status code on failure, on success it may or may not return
230 * depending on the OS.
231 * @retval VINF_SUCCESS
232 * @retval VINF_SYS_MAY_POWER_OFF
233 * @retval VERR_SYS_SHUTDOWN_FAILED
234 * @retval VERR_SYS_CANNOT_POWER_OFF
235 *
236 * @param cMsDelay The delay before the actual reboot. If this is
237 * not supported by the OS, an immediate reboot
238 * will be performed.
239 * @param fFlags Shutdown flags, see RTSYSTEM_SHUTDOWN_XXX.
240 * @param pszLogMsg Message for the log and users about why we're
241 * shutting down.
242 */
243RTDECL(int) RTSystemShutdown(RTMSINTERVAL cMsDelay, uint32_t fFlags, const char *pszLogMsg);
244
245/**
246 * Checks if we're executing inside a virtual machine (VM).
247 *
248 * The current implemention is very simplistic and won't try to detect the
249 * presence of a virtual machine monitor (VMM) unless it openly tells us it is
250 * there.
251 *
252 * @returns true if inside a VM, false if on real hardware.
253 *
254 * @todo If more information is needed, like which VMM it is and which
255 * version and such, add one or two new APIs.
256 */
257RTDECL(bool) RTSystemIsInsideVM(void);
258
259/** @} */
260
261RT_C_DECLS_END
262
263#endif
264
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette