Accessing macOS System Information: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Overview
2	2
3	3		macOS provides four main ways to access system information:
4	4
5	5		- Sysctl interface - An interface used by Unix and Unix-like operating systems to access system hardware and kernel configuration attributes.
6	6		- NSProcessInfo class - A class in the Foundation framework which gives access to a collection of information about the current process.
7	7		- Gestalt Manager - Allows applications to query the running system configuration. Deprecated after 10.7 (Lion) in favour of the NSProcessInfo class or the SysCtl interface.
8	8		- IOKit framework - A framework that implements non-kernel access to I/O Kit objects (drivers and nubs) through the device-interface mechanism.
9	9
10	10		These are described below with code examples.
11	11
12	12		## Sysctl
13	13
14	14		Sysctl provides an interface that allows you to read and, with appropriate privileges, set many kernel attributes in macOS (and Linux and the BSDs). This provides a wealth of information detailing system hardware and configuration attributes which can be useful when debugging or simply optimising your application (eg to take advantage of threads on multi-core CPU systems).
15	15
16	16		The '/usr/local/share/fpcsrc/rtl/darwin/sysctlh.inc' source file is a partial translation of the macOS '/usr/include/sys/sysctl.h' file. For details of the sysctls available, start a Terminal and type 'man sysctl'. Typing 'sysctl-a \\| more' in a Terminal will list all the sysctls.
17	17
18	18		### FPsysctl()
19	19
20	20		> Note: The function definition below for FPsysctl() is for FPC 3.2.0 and later - For FPC 3.0.4 and earlier the first argument is pchar and not pcint. Adjust the code examples accordingly.
21	21
22	22		The fpSysCtl() function allows you to retrieve system information. The data returned from the function comprises integers (integer and int64), strings (AnsiStrings) and C structures (records). The function is defined in `/usr/local/share/fpcsrc/rtl/bsd/sysctl.pp` as:
23	23
24	24		``` pascal
25	25		function FPsysctl (Name: pcint; namelen:cuint; oldp:pointer;oldlenp:psize_t; newp:pointer;newlen:size_t):cint; cdecl; external name 'sysctl';
26	26		```
27	27
28	28		name -- a pointer to a Management Information Base (MIB) array of integers. Each element of this array must contain the correct value to read or write the particular system attribute.
29	29
30	30		namelen -- the length of the array of integers in name.
31	31
32	32		Note: if the old attribute value is not required, the next two variables can be set to Nil and 0.
33	33
34	34		oldp -- a pointer to the buffer into which the value is copied.
35	35
36	36		oldlenp -- the size of the oldp buffer.
37	37
38	38		Note: if the new attribute value is not being set, the next two variables should be set to Nil and 0.
39	39
40	40		newp -- a pointer to the buffer containing the new value to be set.
41	41
42	42		newlen -- the size of the newp buffer.
43	43
44	44		The size of the MIB array depends on the data to be read or written. The first element indicates the level of the information and the subsequent elements indicate the value to read. The top level names are:
45	45
46		-	~~` --------------------------------------------------------------`\~~
47		-	~~` Name Next level names Description`\~~
48		-	~~` are found in`\~~
49		-	~~` --------------------------------------------------------------`\~~
50		-	~~` CTL_DEBUG sys/sysctl.h Debugging`\~~
51		-	~~` CTL_VFS sys/mount.h File system`\~~
52		-	~~` CTL_HW sys/sysctl.h Generic CPU, I/O`\~~
53		-	~~` CTL_KERN sys/sysctl.h High kernel limits`\~~
54		-	~~` CTL_MACHDEP sys/sysctl.h Machine dependent`\~~
55		-	~~` CTL_NET sys/socket.h Networking`\~~
56		-	~~` CTL_USER sys/sysctl.h User-level`\~~
57		-	~~` CTL_VM sys/resources.h Virtual memory`\~~
58		-	~~` --------------------------------------------------------------`~~
	46	+	```
	47	+	--------------------------------------------------------------
	48	+	Name Next level names Description
	49	+	are found in
	50	+	--------------------------------------------------------------
	51	+	CTL_DEBUG sys/sysctl.h Debugging
	52	+	CTL_VFS sys/mount.h File system
	53	+	CTL_HW sys/sysctl.h Generic CPU, I/O
	54	+	CTL_KERN sys/sysctl.h High kernel limits
	55	+	CTL_MACHDEP sys/sysctl.h Machine dependent
	56	+	CTL_NET sys/socket.h Networking
	57	+	CTL_USER sys/sysctl.h User-level
	58	+	CTL_VM sys/resources.h Virtual memory
	59	+	--------------------------------------------------------------
	60	+	```
59	61
60	62		Let's look at CTL_HW. The subsequent elements are found in the system sysctl.h file and are:
61	63
62		-	~~` ------------------------------------------------------------------------------- `\~~
63		-	~~` Name Value Description`\~~
64		-	~~` ------------------------------------------------------------------------------- `\~~
65		-	~~` #define HW_MACHINE 1 /* string: machine class */`\~~
66		-	~~` #define HW_MODEL 2 /* string: specific machine model */`\~~
67		-	~~` #define HW_NCPU 3 /* int: number of cpus */`\~~
68		-	~~` #define HW_BYTEORDER 4 /* int: machine byte order */`\~~
69		-	~~` #define HW_PHYSMEM 5 /* int: total memory */`\~~
70		-	~~` #define HW_USERMEM 6 /* int: non-kernel memory */`\~~
71		-	~~` #define HW_PAGESIZE 7 /* int: software page size */`\~~
72		-	~~` #define HW_DISKNAMES 8 /* strings: disk drive names */`\~~
73		-	~~` #define HW_DISKSTATS 9 /* struct: diskstats[] */`\~~
74		-	~~` #define HW_EPOCH 10 /* int: 0 for Legacy, else NewWorld */`\~~
75		-	~~` #define HW_FLOATINGPT 11 /* int: has HW floating point? */`\~~
76		-	~~` #define HW_MACHINE_ARCH 12 /* string: machine architecture */`\~~
77		-	~~` #define HW_VECTORUNIT 13 /* int: has HW vector unit? */`\~~
78		-	~~` #define HW_BUS_FREQ 14 /* int: Bus Frequency */`\~~
79		-	~~` #define HW_CPU_FREQ 15 /* int: CPU Frequency */`\~~
80		-	~~` #define HW_CACHELINE 16 /* int: Cache Line Size in Bytes */`\~~
81		-	~~` #define HW_L1ICACHESIZE 17 /* int: L1 I Cache Size in Bytes */`\~~
82		-	~~` #define HW_L1DCACHESIZE 18 /* int: L1 D Cache Size in Bytes */`\~~
83		-	~~` #define HW_L2SETTINGS 19 /* int: L2 Cache Settings */`\~~
84		-	~~` #define HW_L2CACHESIZE 20 /* int: L2 Cache Size in Bytes */`\~~
85		-	~~` #define HW_L3SETTINGS 21 /* int: L3 Cache Settings */`\~~
86		-	~~` #define HW_L3CACHESIZE 22 /* int: L3 Cache Size in Bytes */`\~~
87		-	~~` #define HW_TB_FREQ 23 /* int: Bus Frequency */`\~~
88		-	~~` #define HW_MEMSIZE 24 /* uint64_t: physical ram size */`\~~
89		-	~~` #define HW_AVAILCPU 25 /* int: number of available CPUs */`\~~
90		-	~~` #define HW_MAXID 26 /* number of valid hw ids */`\~~
91		-	~~` -------------------------------------------------------------------------------`~~
	64	+	``` pascal
	65	+	-------------------------------------------------------------------------------
	66	+	Name Value Description
	67	+	-------------------------------------------------------------------------------
	68	+	#define HW_MACHINE 1 /* string: machine class */
	69	+	#define HW_MODEL 2 /* string: specific machine model */
	70	+	#define HW_NCPU 3 /* int: number of cpus */
	71	+	#define HW_BYTEORDER 4 /* int: machine byte order */
	72	+	#define HW_PHYSMEM 5 /* int: total memory */
	73	+	#define HW_USERMEM 6 /* int: non-kernel memory */
	74	+	#define HW_PAGESIZE 7 /* int: software page size */
	75	+	#define HW_DISKNAMES 8 /* strings: disk drive names */
	76	+	#define HW_DISKSTATS 9 /* struct: diskstats[] */
	77	+	#define HW_EPOCH 10 /* int: 0 for Legacy, else NewWorld */
	78	+	#define HW_FLOATINGPT 11 /* int: has HW floating point? */
	79	+	#define HW_MACHINE_ARCH 12 /* string: machine architecture */
	80	+	#define HW_VECTORUNIT 13 /* int: has HW vector unit? */
	81	+	#define HW_BUS_FREQ 14 /* int: Bus Frequency */
	82	+	#define HW_CPU_FREQ 15 /* int: CPU Frequency */
	83	+	#define HW_CACHELINE 16 /* int: Cache Line Size in Bytes */
	84	+	#define HW_L1ICACHESIZE 17 /* int: L1 I Cache Size in Bytes */
	85	+	#define HW_L1DCACHESIZE 18 /* int: L1 D Cache Size in Bytes */
	86	+	#define HW_L2SETTINGS 19 /* int: L2 Cache Settings */
	87	+	#define HW_L2CACHESIZE 20 /* int: L2 Cache Size in Bytes */
	88	+	#define HW_L3SETTINGS 21 /* int: L3 Cache Settings */
	89	+	#define HW_L3CACHESIZE 22 /* int: L3 Cache Size in Bytes */
	90	+	#define HW_TB_FREQ 23 /* int: Bus Frequency */
	91	+	#define HW_MEMSIZE 24 /* uint64_t: physical ram size */
	92	+	#define HW_AVAILCPU 25 /* int: number of available CPUs */
	93	+	#define HW_MAXID 26 /* number of valid hw ids */
	94	+	-------------------------------------------------------------------------------
	95	+	```
92	96
93	97		Armed with this information, we can now find out the number of CPUs:
94	98
95	99		``` pascal
96	100		// The full source code for this example is available from:
97	101		// https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/fpc_sysctls/num_cpu.pas
98	102		...
99	103		Uses
100	104		SysUtils, SysCtl, Unix;
101	105		...
102	106		function NumberOfCPU: Integer;
103	107
104	108		var
105	109		mib: array[0..1] of Integer;
106	110		status : Integer;
107	111		len : size_t;
108	112
109	113		begin
110	114		mib[0] := CTL_HW;
111	115		mib[1] := HW_NCPU;
112	116
113	117		len := SizeOf(Result);
114	118		status := fpSysCtl(PCInt(@mib), Length(mib), @Result, @len, Nil, 0);
115	119		if status <> 0 then RaiseLastOSError;
116	120		end;
117	121		```
118	122
119	123		The above code returns the number of CPUs in an integer; you need to check the C header file to determine what is being returned (an integer, int64, string, struct/record).
120	124
121	125		There is a possible issue with the above because if you have, for example, an Intel CPU with hyperthreading. One guess. Yes, it will return the total number of threads and not the number of CPUs or even the number of physical cores. HW_NCPU is pretty much deprecated these days as a useful attribute. Instead, we can retrieve the number of CPU packages, physical CPUs (cores) or logical CPUs (the same as HW_NCPU). To do so requires the use of a second function 'FPsysctlbyname'.
122	126
123	127		However, before we move on, let's look at retrieving a string with FPsysctl() which is a little different than retrieving an integer.
124	128
125	129		``` pascal
126	130		// The full source code for this example is available from:
127	131		// https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/fpc_sysctls/hardware_model.pas
128	132		...
129	133		Uses
130	134		SysUtils, SysCtl, Unix;
131	135		...
132	136		function HWmodel : AnsiString;
133	137
134	138		var
135	139		mib : array[0..1] of Integer;
136	140		status : Integer;
137	141		len : size_t;
138	142		p : PChar;
139	143
140	144		begin
141	145		mib[0] := CTL_HW;
142	146		mib[1] := HW_MODEL;
143	147
144	148		status := fpSysCtl(PCInt(@mib), Length(mib), Nil, @len, Nil, 0);
145	149		if status <> 0 then RaiseLastOSError;
146	150
147	151		GetMem(p, len);
148	152
149	153		try
150	154		status := fpSysCtl(PCInt(@mib), Length(mib), p, @len, Nil, 0);
151	155		if status <> 0 then RaiseLastOSError;
152	156		Result := p;
153	157		finally
154	158		FreeMem(p);
155	159		end;
156	160		end;
157	161		```
158	162
159	163		Notice that this time we needed two calls to FPsysctl() - one to find out the size of the buffer required to hold the string value, and the second to actually retrieve the string value into that buffer. On my Apple computer this returns the string "Macmini8,1" - the 2018 Mac mini.
160	164
161	165		No, we're not quite ready to move on yet... we still need to see how to retrieve information in a C structure (Pascal record).
162	166
163	167		``` pascal
164	168		// The full source code for this example is available from:
165	169		// https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/fpc_sysctls/swap_usage.pas
166	170		...
167	171		Uses
168	172		SysUtils, SysCtl, Unix;
169	173		...
170	174		function SwapUsage: String;
171	175
172	176		type
173	177		swapinfo = record
174	178		xsu_total : Int64;
175	179		xsu_avail : Int64;
176	180		xsu_used : Int64;
177	181		xsu_pagesize : Integer;
178	182		xsu_encrypted: Boolean;
179	183		end;
180	184
181	185		const
182	186		VM_SWAPUSAGE = 5;
183	187
184	188		var
185	189		mib : array[0..1] of Integer;
186	190		status : Integer;
187	191		len : size_t;
188	192		swap : swapinfo;
189	193		SwapEncrypted: String;
190	194
191	195		begin
192	196		mib[0] := CTL_VM;
193	197		mib[1] := VM_SWAPUSAGE;
194	198		swap := Default(swapinfo);
195	199
196	200		FillChar(swap, sizeof(swap), 0);
197	201		len := sizeof(swap);
198	202
199	203		status := fpSysCtl(PCInt(@mib), Length(mib), @swap, @len, Nil, 0);
200	204		if status <> 0 then RaiseLastOSError;
201	205
202	206		if(swap.xsu_encrypted = true) then
203	207		SwapEncrypted := 'Yes' else SwapEncrypted := 'No';
204	208
205	209		Result := 'Swap total: ' + FloatToStr(Round(swap.xsu_total /1024 /1024)) + ' MB'
206	210		+ LineEnding + 'Swap used: ' + FloatToStr(Round(swap.xsu_used /1024 /1024)) + ' MB'
207	211		+ LineEnding + 'Swap free: ' + FloatToStr(Round(swap.xsu_avail /1024 /1024)) + ' MB'
208	212		+ LineEnding + 'Swap page size: ' + IntToStr(swap.xsu_pagesize) + ' bytes'
209	213		+ LineEnding + 'Swap encrypted: ' + SwapEncrypted + LineEnding;
210	214		end;
211	215		```
212	216
213	217		> Note: If your computer has not used any swap, then the results for Swap total, used and free will all be zero.
214	218
215	219		On my computer this returned:
216	220
217		-	~~` Swap total: 1024 MB`\~~
218		-	~~` Swap used: 191 MB`\~~
219		-	~~` Swap free: 833 MB`\~~
220		-	~~` Swap page size: 4096 bytes`\~~
221		-	~~` Swap encrypted: Yes`~~
	221	+	```
	222	+	Swap total: 1024 MB
	223	+	Swap used: 191 MB
	224	+	Swap free: 833 MB
	225	+	Swap page size: 4096 bytes
	226	+	Swap encrypted: Yes
	227	+	```
222	228
223	229		The swapinfo record was pretty easily translated from the C structure found in the system `sysctl.h` file:
224	230
225	231		``` c
226	232		struct xsw_usage {
227	233		u_int64_t xsu_total;
228	234		u_int64_t xsu_avail;
229	235		u_int64_t xsu_used;
230	236		u_int32_t xsu_pagesize;
231	237		boolean_t xsu_encrypted;
232	238		};
233	239		```
234	240
235	241		We also defined the MIB constant VM_SWAPUSAGE by looking at the system `sysctl.h` file. Why? Because Free Pascal 3.2.0 and earlier are missing this identifier (fixed in FPC 3.2.2). So, we looked it up and found:
236	242
237	243		``` c
238	244		#define VM_SWAPUSAGE 5 /* total swap usage */
239	245		```
240	246
241	247		Finally, yes, it is time to move on to the FPsysctlbyname() function.
242	248
243	249		### FPsysctlbyname
244	250
245	251		The FPsysctlbyname function is defined in '/usr/local/share/fpcsrc/rtl/bsd/sysctl.pp' as:
246	252
247	253		``` pascal
248	254		function FPsysctlbyname (Name: pchar; oldp:pointer;oldlenp:psize_t; newp:pointer;newlen:size_t):cint; cdecl; external name 'sysctlbyname';
249	255		```
250	256
251	257		There. Not really very different from the FPsysctl() function. Is that a sigh of relief? So let's look at finally retrieving the number of physical CPU cores.
252	258
253	259		``` pascal
254	260		// Full source code for this example is available from:
255	261		// https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/fpc_sysctls/num_cores.pas
256	262		...
257	263		{$mode objfpc}
258	264		...
259	265
260	266		Uses
261	267		SysCtl, SysUtils, Unix;
262	268
263	269		function NumberOfCores: Integer;
264	270
265	271		var
266	272		status : Integer;
267	273		len : size_t;
268	274
269	275		begin
270	276		len := SizeOf(Result);
271	277
272	278		status := fpSysCtlByName('hw.physicalcpu', @Result, @len, Nil, 0);
273	279		if status <> 0 then RaiseLastOSError;
274	280		end;
275	281		```
276	282
277	283		On my 2018 Mac mini this returns the correct number of cores: 6. Where do you find the special incantation hw.physicalcpu ? Yes, in the system `sysctl.h` file. Here's a brief excerpt of some of the hardware selectors:
278	284
279		-	~~` These are the support HW selectors for sysctlbyname. Parameters that are byte counts or frequencies are 64 bit numbers.`\~~
280		-	~~` All other parameters are 32 bit numbers.`\~~
281		-	~~` `\~~
282		-	~~` hw.memsize - The number of bytes of physical memory in the system.`\~~
283		-	~~` hw.ncpu - The maximum number of processors that could be available this boot.`\~~
284		-	~~` Use this value for sizing of static per processor arrays; i.e. processor load statistics.`\~~
285		-	~~` hw.activecpu - The number of processors currently available for executing threads.`\~~
286		-	~~` Use this number to determine the number threads to create in SMP aware applications.`\~~
287		-	~~` This number can change when power management modes are changed.`\~~
288		-	~~` hw.physicalcpu - The number of physical processors available in the current power management mode.`\~~
289		-	~~` hw.physicalcpu_max - The maximum number of physical processors that could be available this boot`\~~
290		-	~~` hw.logicalcpu - The number of logical processors available in the current power management mode.`\~~
291		-	~~` hw.logicalcpu_max - The maximum number of logical processors that could be available this boot`\~~
292		-	~~` hw.tbfrequency - This gives the time base frequency used by the OS and is the basis of all timing services.`\~~
293		-	~~` In general is is better to use mach's or higher level timing services, but this value`\~~
294		-	~~` is needed to convert the PPC Time Base registers to real time.`\~~
295		-	~~` hw.cpufrequency - These values provide the current, min and max cpu frequency. The min and max are for`\~~
296		-	~~` hw.cpufrequency_max - all power management modes. The current frequency is the max frequency in the current mode.`\~~
297		-	~~` hw.cpufrequency_min - All frequencies are in Hz.`\~~
298		-	~~` hw.busfrequency - These values provide the current, min and max bus frequency. The min and max are for`\~~
299		-	~~` hw.busfrequency_max - all power management modes. The current frequency is the max frequency in the current mode.`\~~
300		-	~~` hw.busfrequency_min - All frequencies are in Hz.`\~~
301		-	~~` hw.cputype - These values provide the mach-o cpu type and subtype. A complete list is in <mach/machine.h>`\~~
302		-	~~` hw.cpusubtype - These values should be used to determine what processor family the running cpu is from so that`\~~
303		-	~~` the best binary can be chosen, or the best dynamic code generated. They should not be used`\~~
304		-	~~` to determine if a given processor feature is available.`\~~
305		-	~~` hw.cputhreadtype - This value will be present if the processor supports threads. Like hw.cpusubtype this selector`\~~
306		-	~~` should not be used to infer features, and only used to name the processors thread architecture.`\~~
307		-	~~` The values are defined in <mach/machine.h>`\~~
308		-	~~` hw.byteorder - Gives the byte order of the processor. 4321 for big endian, 1234 for little.`\~~
309		-	~~` hw.pagesize - Gives the size in bytes of the pages used by the processor and VM system.`\~~
310		-	~~` hw.cachelinesize - Gives the size in bytes of the processor's cache lines.`\~~
311		-	~~` This value should be use to control the strides of loops that use cache control instructions`\~~
312		-	~~` like dcbz, dcbt or dcbst.`\~~
313		-	~~` hw.l1dcachesize - These values provide the size in bytes of the L1, L2 and L3 caches. If a cache is not present`\~~
314		-	~~` hw.l1icachesize - then the selector will return an error.`\~~
315		-	~~` hw.l2cachesize -`\~~
316		-	~~` hw.l3cachesize -`\~~
317		-	~~` hw.packages - Gives the number of processor packages.`~~
	285	+	``` pascal
	286	+	These are the support HW selectors for sysctlbyname. Parameters that are byte counts or frequencies are 64 bit numbers.
	287	+	All other parameters are 32 bit numbers.
	288	+
	289	+	hw.memsize - The number of bytes of physical memory in the system.
	290	+	hw.ncpu - The maximum number of processors that could be available this boot.
	291	+	Use this value for sizing of static per processor arrays; i.e. processor load statistics.
	292	+	hw.activecpu - The number of processors currently available for executing threads.
	293	+	Use this number to determine the number threads to create in SMP aware applications.
	294	+	This number can change when power management modes are changed.
	295	+	hw.physicalcpu - The number of physical processors available in the current power management mode.
	296	+	hw.physicalcpu_max - The maximum number of physical processors that could be available this boot
	297	+	hw.logicalcpu - The number of logical processors available in the current power management mode.
	298	+	hw.logicalcpu_max - The maximum number of logical processors that could be available this boot
	299	+	hw.tbfrequency - This gives the time base frequency used by the OS and is the basis of all timing services.
	300	+	In general is is better to use mach's or higher level timing services, but this value
	301	+	is needed to convert the PPC Time Base registers to real time.
	302	+	hw.cpufrequency - These values provide the current, min and max cpu frequency. The min and max are for
	303	+	hw.cpufrequency_max - all power management modes. The current frequency is the max frequency in the current mode.
	304	+	hw.cpufrequency_min - All frequencies are in Hz.
	305	+	hw.busfrequency - These values provide the current, min and max bus frequency. The min and max are for
	306	+	hw.busfrequency_max - all power management modes. The current frequency is the max frequency in the current mode.
	307	+	hw.busfrequency_min - All frequencies are in Hz.
	308	+	hw.cputype - These values provide the mach-o cpu type and subtype. A complete list is in <mach/machine.h>
	309	+	hw.cpusubtype - These values should be used to determine what processor family the running cpu is from so that
	310	+	the best binary can be chosen, or the best dynamic code generated. They should not be used
	311	+	to determine if a given processor feature is available.
	312	+	hw.cputhreadtype - This value will be present if the processor supports threads. Like hw.cpusubtype this selector
	313	+	should not be used to infer features, and only used to name the processors thread architecture.
	314	+	The values are defined in <mach/machine.h>
	315	+	hw.byteorder - Gives the byte order of the processor. 4321 for big endian, 1234 for little.
	316	+	hw.pagesize - Gives the size in bytes of the pages used by the processor and VM system.
	317	+	hw.cachelinesize - Gives the size in bytes of the processor's cache lines.
	318	+	This value should be use to control the strides of loops that use cache control instructions
	319	+	like dcbz, dcbt or dcbst.
	320	+	hw.l1dcachesize - These values provide the size in bytes of the L1, L2 and L3 caches. If a cache is not present
	321	+	hw.l1icachesize - then the selector will return an error.
	322	+	hw.l2cachesize -
	323	+	hw.l3cachesize -
	324	+	hw.packages - Gives the number of processor packages.
	325	+	```
318	326
319	327		If you prefer, you can instead use the `sysctl` command line utility in a Terminal to list all the hw selectors with the `sysctl hw` command.
320	328
321	329		Retrieving a string value, rather than an integer, is again reminiscent of FPsysctl(). Two calls to FPsysctlbyname() are needed: (1) to find out the size of the buffer to hold the string to be returned and (2) to return the string value into that buffer. Don't forget to allocate memory for the buffer before the second call!
322	330
323	331		``` pascal
324	332		// Full source code for this example is available from:
325	333		// https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/fpc_sysctls/brand_cpu.pas
326	334		...
327	335		{$mode objfpc}
328	336		...
329	337
330	338		Uses
331	339		SysCtl, SysUtils, Unix;
332	340
333	341		function BrandOfCPU: AnsiString;
334	342
335	343		var
336	344		status : Integer;
337	345		len : size_t;
338	346		p : PChar;
339	347
340	348		begin
341	349		status := fpSysCtlByName('machdep.cpu.brand_string', Nil, @len, Nil, 0);
342	350		if status <> 0 then RaiseLastOSError;
343	351
344	352		GetMem(p, len);
345	353
346	354		try
347	355		status := fpSysCtlByName('machdep.cpu.brand_string', p, @len, Nil, 0);
348	356		if status <> 0 then RaiseLastOSError;
349	357		Result := p;
350	358		finally
351	359		FreeMem(p);
352	360		end;
353	361		end;
354	362		```
355	363
356	364		On my 2018 Mac mini computer, this returns the very informative string: Intel(R) Core(TM) i7-8700B CPU @ 3.20GHz. On my 2020 Mac mini computer, this returns the somewhat less informative string: Apple M1.
357	365
358	366		Oh, you noticed, I changed the top level identifier from hw to machdep (machine dependent). Again, consult `sysctl.h` or use the `sysctl` command line utility in a Terminal.
359	367
360	368		``` pascal
361	369		// Full source code for this example is available from:
362	370		// https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/fpc_sysctls/os_version.pas
363	371
364	372		// Note: The kern.osproductversion attribute was added to the Darwin kernel in December 2018
365	373		// https://github.com/apple/darwin-xnu/commit/5bbb823c13f3ab1ab58878f96b35433a29882676
366	374
367	375		Program os_version;
368	376
369	377		{$mode objfpc}
370	378
371	379		Uses
372	380		SysCtl, SysUtils, Unix;
373	381
374	382		function OS_version : AnsiString;
375	383
376	384		var
377	385		status : Integer;
378	386		len : size_t;
379	387		p : PChar;
380	388
381	389		begin
382	390		status := fpSysCtlByName('kern.osproductversion', Nil, @len, Nil, 0);
383	391		if status <> 0 then RaiseLastOSError;
384	392
385	393		GetMem(p, len);
386	394
387	395		try
388	396		status := fpSysCtlByName('kern.osproductversion', p, @len, Nil, 0);
389	397		if status <> 0 then RaiseLastOSError;
390	398		Result := p;
391	399		finally
392	400		FreeMem(p);
393	401		end;
394	402		end;
395	403
396	404		begin
397	405		WriteLn(OS_version);
398	406		end.
399	407		```
400	408
401	409		The above FPC example program will return the operating system version. On my M1 processor Mac mini this was "11.2.3" (Big Sur).
402	410
403	411		### Last words
404	412
405	413		For the optimised, performance fiends out there, the man page for these functions notes that the FPsysctl() function runs in about a third the time as the same request made via the FPsysctlbyname() function.
406	414
407	415		It should be noted that many of the sysctl attributes are read-only, but there are also quite a few that can be changed. I've left changing a sysctl attribute as an exercise for you dear reader. It should be simple if you study the definitions of the function parameters, paying particular attention to newp and newlen.
408	416
409	417		## NSProcessinfo
410	418
411	419		Each macOS process has a single, shared NSProcessInfo object, known as a process information agent. This process information agent can return information such as arguments, environment variables, host name, and process name. The processInfo class method returns the shared agent for the current process—that is, the process whose object sent the message.
412	420
413	421		### Properties
414	422
415	423		\| Property \| Description \|
416	424		\|----\|----\|
417	425		\| processInfo \| Returns the process information agent for the process. An NSProcessInfo object is created the first time this method is invoked, and that same object is returned on each subsequent invocation. \|
418	426		\| arguments \| Array of strings with the command-line arguments for the process. \|
419	427		\| environment \| The variable names (keys) and their values in the environment from which the process was launched. \|
420	428		\| globallyUniqueString \| Global unique identifier for the process. The global ID for the process includes the host name, process ID, and a time stamp, which ensures that the ID is unique for the network. This property generates a new string each time its getter is invoked, and it uses a counter to guarantee that strings created from the same process are unique. \|
421	429		\| processIdentifier \| The identifier of the process (often called process ID or PID). \|
422	430		\| processName \| The name of the process. \|
423	431		\| userName \| Returns the account name of the current user. macOS 10.12+ \|
424	432		\| fullUserName \| Returns the full name of the current user. macOS 10.12+ \|
425	433		\| hostName \| The name of the host computer on which the process is executing. \|
426	434		\| operatingSystemVersionString \| A string containing the version of the operating system on which the process is executing. macOS 10.2+ \|
427	435		\| operatingSystemVersion \| The version of the operating system on which the process is executing. macOS 10.10+ \|
428	436		\| processorCount \| The number of processing cores available on the computer. Equivalent to: `sysctl -n hw.ncpu`. macOS 10.5+ \|
429	437		\| activeProcessorCount \| The number of active processing cores available on the computer. Equivalent to: `sysctl -n hw.logicalcpu`. macOS 10.5+ \|
430	438		\| physicalMemory \| The amount of physical memory on the computer in bytes. macOS 10.5+ \|
431	439		\| systemUptime \| The amount of time in seconds that the system has been awake since the last time it was restarted. macOS 10.6+ \|
432	440		\| thermalState \| The current thermal state of the system: Nominal, Fair, Serious or Critical. macOS 10.10.3+ \|
433	441		\| automaticTerminationSupportEnabled \| A Boolean value indicating whether the app supports automatic termination. Currently, setting this property to False has no effect. macOS 10.7+ \|
434	442		\| \| \|
435	443
436	444		### Methods
437	445
438	446		\| Method \| Description \|
439	447		\|----\|----\|
440	448		\| isOperatingSystemAtLeastVersion \| Returns a Boolean value indicating whether the version of the operating system on which the process is executing is the same or later than the given version. macOS 10.10+ \|
441	449
442	450		### Example code
443	451
444	452		``` pascal
445	453		unit Unit1;
446	454
447	455		{$mode objfpc}{$H+}
448	456		{$modeswitch objectivec1}
449	457
450	458		interface
451	459
452	460		uses
453	461		Classes, SysUtils, Forms, Dialogs, StdCtrls,
454	462		ctypes, // needed for cint
455	463		typinfo, // needed for GetEnumName
456	464		CocoaAll; // needed for NS...
457	465
458	466		type
459	467		// From HERE...
460	468		NSProcessInfoThermalState = (
461	469		Nominal, // within the normal range; no corrective action is required.
462	470		Fair, // thermal state is slightly elevated and the fan is audible.
463	471		Serious, // fan is at maximum speed; performance may be affected;
464	472		// applications should reduce use of CPU, GPU, and any I/O.
465	473		Critical); // thermal state severely affects performance; need immediate cooling;
466	474		// applications should reduce use of CPU, GPU, and any I/O to minimum
467	475		// required for user interaction; stop using peripherals such as cameras.
468	476
469	477		NSOperatingSystemVersion = record
470	478		majorVersion: NSInteger;
471	479		minorVersion: NSInteger;
472	480		patchVersion: NSInteger;
473	481		end;
474	482
475	483		NSProcessInfo = objcclass external (NSObject)
476	484		private
477	485		environment_: NSDictionary;
478	486		arguments_: NSArray;
479	487		hostName_: NSString;
480	488		name: NSString;
481	489		automaticTerminationOptOutCounter: NSInteger;
482	490		public
483	491		class function processInfo: NSProcessInfo; message 'processInfo';
484	492		function environment: NSDictionary; message 'environment';
485	493		function arguments: NSArray; message 'arguments';
486	494		function hostName: NSString; message 'hostName';
487	495		procedure setProcessName(newValue: NSString); message 'setProcessName:';
488	496		function processName: NSString; message 'processName';
489	497		function processIdentifier: cint; message 'processIdentifier';
490	498		function globallyUniqueString: NSString; message 'globallyUniqueString';
491	499		function operatingSystemVersionString: NSString; message 'operatingSystemVersionString';
492	500		function userName: NSString; message 'userName';
493	501		function fullUserName: NSString; message 'fullUserName';
494	502		function operatingSystemVersion: NSOperatingSystemVersion; message 'operatingSystemVersion';
495	503		function processorCount: NSUInteger; message 'processorCount';
496	504		function activeProcessorCount: NSUInteger; message 'activeProcessorCount';
497	505		function physicalMemory: culonglong; message 'physicalMemory';
498	506		function isOperatingSystemAtLeastVersion (os_version: NSOperatingSystemVersion): Boolean; message 'isOperatingSystemAtLeastVersion:';
499	507		function systemUptime: NSTimeInterval; message 'systemUptime';
500	508		function thermalState: NSInteger; message 'thermalState';
501	509		{procedure disableSuddenTermination; message 'disableSuddenTermination';
502	510		procedure enableSuddenTermination; message 'enableSuddenTermination';
503	511		procedure disableAutomaticTermination (reason: NSString); message 'disableAutomaticTermination:';
504	512		procedure enableAutomaticTermination (reason: NSString); message 'enableAutomaticTermination:';}
505	513		procedure setAutomaticTerminationSupportEnabled(newValue: Boolean); message 'setAutomaticTerminationSupportEnabled:';
506	514		function automaticTerminationSupportEnabled: Boolean; message 'automaticTerminationSupportEnabled';
507	515		end;
508	516		// ... To HERE is ONLY NEEDED if you are using FPC 3.0.4 or earlier. FPC 3.2.0 does not need this section.
509	517
510	518		{ TForm1 }
511	519
512	520		TForm1 = Class(TForm)
513	521		Button1: TButton;
514	522		Memo1: TMemo;
515	523		procedure Button1Click(Sender: TObject);
516	524		private
517	525
518	526		public
519	527
520	528		end;
521	529
522	530		var
523	531		Form1: TForm1;
524	532
525	533		implementation
526	534
527	535		{$R *.lfm}
528	536
529	537		{ TForm1 }
530	538
531	539		procedure ProcessInfo;
532	540		var
533	541		thermalState : String;
534	542		myDictionary : NSDictionary;
535	543		i : Byte = 0;
536	544		minOsVer : NSOperatingSystemVersion;
537	545		begin
538	546		Form1.Memo1.Lines.Clear;
539	547
540	548		Form1.Memo1.Lines.Add('Processor count: '
541	549		+ IntToStr(NSProcessInfo.ProcessInfo.processorCount)
542	550		+ LineEnding + 'Active processors: '
543	551		+ IntToStr(NSProcessInfo.ProcessInfo.activeProcessorCount)
544	552		+ LineEnding + 'Physical memory: '
545	553		+ FloatToStr(NSProcessInfo.ProcessInfo.physicalMemory / 1024 / 1024 / 1024) + 'GB'
546	554		+ LinEending + 'Process name: '
547	555		+ NSProcessInfo.ProcessInfo.processName.UTF8String
548	556		+ LinEending + 'PID: '
549	557		+ IntToStr(NSProcessInfo.ProcessInfo.processIdentifier)
550	558		+ LineEnding + 'Uptime: '
551	559		+ FormatFloat('0.00', NSProcessInfo.ProcessInfo.systemUptime / 60 / 60 / 24) + ' days'
552	560		+ LineEnding + 'Operating system: '
553	561		+ NSProcessInfo.ProcessInfo.operatingSystemVersionString.UTF8String
554	562		+ LineEnding
555	563		+ 'Major: ' + IntToStr(NSProcessInfo.ProcessInfo.OperatingSystemVersion.majorVersion)
556	564		+ ' Minor: ' + IntToStr(NSProcessInfo.ProcessInfo.OperatingSystemVersion.minorVersion)
557	565		+ ' Patch: ' + IntToStr(NSProcessInfo.ProcessInfo.OperatingSystemVersion.patchVersion)
558	566		+ LineEnding + 'Hostname: '
559	567		+ NSProcessInfo.ProcessInfo.hostName.UTF8String
560	568		+ LineEnding + 'Globally unique string: '
561	569		+ NSProcessInfo.ProcessInfo.globallyUniqueString.UTF8String
562	570		+ LineEnding + 'Username: '
563	571		+ NSProcessInfo.ProcessInfo.userName.UTF8String
564	572		+ LineEnding + 'Full Username: '
565	573		+ NSProcessInfo.ProcessInfo.fullUserName.UTF8String
566	574		+ LineEnding
567	575		);
568	576
569	577		myDictionary := NSProcessInfo.ProcessInfo.environment;
570	578		for i := 0 to (myDictionary.count - 1) do
571	579		begin
572	580		Form1.Memo1.Lines.Add('Env Var: '
573	581		+ myDictionary.allKeys.objectAtIndex(i).UTF8String
574	582		+ ' = '
575	583		+ myDictionary.allValues.objectAtIndex(i).UTF8String
576	584		);
577	585		end;
578	586
579	587		ThermalState := GetEnumName(TypeInfo(NSProcessInfoThermalState), Ord(NSProcessInfo.ProcessInfo.thermalState));
580	588		Form1.Memo1.Lines.Add(LineEnding + 'Thermal state: ' + ThermalState
581	589		);
582	590
583	591		// Setup minimum OS version
584	592		minOsVer.majorVersion:= 10;
585	593		minOsVer.minorVersion:= 14;
586	594		minOsVer.patchVersion:= 6;
587	595
588	596		if(NSProcessInfo.ProcessInfo.isOperatingSystemAtLeastVersion(minOSVer)) then
589	597		Form1.Memo1.Lines.Add(LineEnding + 'OS version is at least 10.14.6' + LineEnding)
590	598		else
591	599		Form1.Memo1.Lines.Add(LineEnding + 'OS version is NOT at least 10.14.6' + LineEnding)
592	600		end;
593	601
594	602		procedure TForm1.Button1Click(Sender: TObject);
595	603		begin
596	604		processInfo;
597	605		end;
598	606
599	607		end.
600	608		```
601	609
602	610		## Gestalt Manager
603	611
604	612		Despite Apple's deprecation of the Gestalt Manager in favour of the NSProcessInfo class or the SysCtl Interface, there are still occasions when you will need to use it. For example, the NSProcessInfo instance property `OperatingSystemVersion` is only available from macOS 10.10 (Yosemite) onwards according to Apple's documentation, although it seems to also work in macOS 10.9 (Mavericks).
605	613
606	614		So what do you do if you want to check the version of the operating system across all versions back to Mac OS X 10.0 (Cheetah)? The example code below holds the solution.
607	615
608	616		### Example: Retrieving OS version from Mac OS X 10.0+
609	617
610	618		``` pascal
611	619		unit Unit1;
612	620
613	621		{$mode objfpc}{$H+}
614	622		{$modeswitch objectivec2}
615	623
616	624		interface
617	625
618	626		uses
619	627		Classes, SysUtils, Forms, Dialogs, StdCtrls, ExtCtrls,
620	628		MacOSAll,
621	629		CocoaAll;
622	630
623	631		type
624	632
625	633		{ TForm1 }
626	634
627	635		TForm1 = Class(TForm)
628	636		Memo1: TMemo;
629	637		Button1: TButton;
630	638		procedure Button1Click(Sender: TObject);
631	639		private
632	640		public
633	641
634	642		end;
635	643
636	644		var
637	645		Form1: TForm1;
638	646		counter: Int64;
639	647
640	648		implementation
641	649
642	650		{$R *.lfm}
643	651
644	652		{ TForm1 }
645	653
646	654		procedure ProcessInfo;
647	655		begin
648	656		Form1.Memo1.Lines.Clear;
649	657
650	658		Form1.Memo1.Lines.Add('macOS version: '
651	659		+ IntToStr(NSProcessInfo.ProcessInfo.operatingSystemVersion.majorVersion)
652	660		+ '.'
653	661		+ IntToStr(NSProcessInfo.ProcessInfo.operatingSystemVersion.minorVersion)
654	662		+ '.'
655	663		+ IntToStr(NSProcessInfo.ProcessInfo.operatingSystemVersion.patchVersion)
656	664		);
657	665		end;
658	666
659	667		Procedure GestaltInfo;
660	668		var
661	669		majorVersion: LongInt = 0;
662	670		minorVersion: LongInt = 0;
663	671		patchVersion: LongInt = 0;
664	672		begin
665	673		Form1.Memo1.Lines.Clear;
666	674		Form1.Memo1.Lines.Add('Trying another way...');
667	675
668	676		Gestalt(gestaltSystemVersionMajor, majorVersion);
669	677		Gestalt(gestaltSystemVersionMinor, minorVersion);
670	678		Gestalt(gestaltSystemVersionBugFix, patchVersion);
671	679
672	680		Form1.Memo1.Lines.Add('macOS version: ' + IntToStr(majorVersion) + '.' +
673	681		IntToStr(minorVersion) + '.' + IntToStr(patchVersion));
674	682		end;
675	683
676	684		procedure TForm1.Button1Click(Sender: TObject);
677	685		var
678	686		aSEL : SEL;
679	687		begin
680	688		// Check whether OS version responds to this selector
681	689		aSEL := objcselector('operatingSystemVersion');
682	690		if NSProcessInfo.processInfo.respondsToSelector(aSEL) then
683	691		ProcessInfo
684	692		// Otherwise fallback to the deprecated Gestalt Manager
685	693		else
686	694		GestaltInfo;
687	695		end;
688	696
689	697		end.
690	698		```
691	699
692	700		## IOKit
693	701
694	702		IOKit is Apple’s object-oriented framework for developing device drivers for macOS. While the main use of the IOKit framework is for developers creating device drivers that are to be resident in the kernel, it is also of use to application developers who can using an IOKit device interface to communicate with the Apple hardware.
695	703
696	704		While the focus of this section is on accessing macOS system information, it should be noted that the IOKit framework has been deprecated by Apple in macOS 10.15 Catalina in favour of the DriverKit framework which debuted in that version of macOS. DriverKit provides a fully modernized replacement for IOKit to create device drivers. System extensions and drivers built with DriverKit run in user space, where they can't compromise the security or stability of macOS.
697	705
698	706		### Example: Retrieving the platform serial number
699	707
700	708		``` pascal
701	709		program project1;
702	710
703	711		{$mode objfpc}{$H+}
704	712		{$modeswitch cvar}
705	713		{$linkframework IOKit}
706	714
707	715		uses
708	716		ctypes, Classes, MacOSAll;
709	717		{ you can add units after this };
710	718
711	719		type
712	720		kern_return_t = cint; // if you use "integer" then you don't need "ctypes" unit
713	721		io_object_t = mach_port_t;
714	722		io_registry_entry_t = io_object_t;
715	723
716	724		io_string_t = array [0..511] of ansichar;
717	725		IOOptionBits = UInt32;
718	726
719	727		const
720	728		kIOPlatformSerialNumber = 'IOPlatformSerialNumber';
721	729
722	730		var
723	731		kIOMasterPortDefault:mach_port_t; cvar; external;
724	732
725	733		function IORegistryEntryFromPath( masterPort: mach_port_t; const path: io_string_t): io_registry_entry_t; cdecl; external;
726	734		function IORegistryEntryCreateCFProperty(entry: io_registry_entry_t; key: CFStringRef; allocator:CFAllocatorRef; options: IOOptionBits): CFTypeRef; cdecl; external;
727	735		function IOObjectRelease(entry: io_registry_entry_t): kern_return_t; cdecl; external;
728	736
729	737		function get_platform_serial_num: string;
730	738		var
731	739		ioRegistryRoot :io_registry_entry_t;
732	740		serialnumCf :CFStringRef;
733	741		l :integer;
734	742		begin
735	743		ioRegistryRoot := IORegistryEntryFromPath(kIOMasterPortDefault, 'IOService:/');
736	744		serialnumCf := CFStringRef (IORegistryEntryCreateCFProperty(ioRegistryRoot, CFSTR(kIOPlatformSerialNumber), kCFAllocatorDefault, 0));
737	745		IOObjectRelease(ioRegistryRoot);
738	746		SetLength(Result, 32);
739	747		CFStringGetCString(serialnumCf, @Result[1], length(Result), kCFStringEncodingMacRoman);
740	748		CFRelease(serialnumCf);
741	749		l:=StrLen(@Result[1]);
742	750		SetLength(Result, l);
743	751		end;
744	752
745	753		begin
746	754		WriteLn('Platform serial number: ', get_platform_serial_num);
747	755		end.
748	756		```
749	757
750	758		### Example: Retrieving the platform UUID
751	759
752	760		A UUID (Universally Unique Identifier) is a 16-byte long number. It is normally expressed in a standard format of characters representing hexadecimal digits. UUIDs were formerly known as Globally Unique Identifiers (GUIDs), but are now officially Universally Unique Identifiers, or UUIDs, and are governed by Open Software Foundation, ISO/IEC, and IETF standards.
753	761
754	762		``` pascal
755	763		program project1;
756	764
757	765		{$mode objfpc}{$H+}
758	766		{$modeswitch cvar}
759	767		{$linkframework IOKit}
760	768
761	769		uses
762	770		ctypes, Classes, MacOSAll
763	771		{ you can add units after this };
764	772
765	773		type
766	774		kern_return_t = cint; // if you use "integer" then you don't need "ctypes" unit
767	775		io_object_t = mach_port_t;
768	776		io_registry_entry_t = io_object_t;
769	777
770	778		io_string_t = array [0..511] of ansichar;
771	779		IOOptionBits = UInt32;
772	780
773	781		const
774	782		kIOPlatformUUIDKey = 'IOPlatformUUID';
775	783
776	784		var
777	785		kIOMasterPortDefault:mach_port_t; cvar; external;
778	786
779	787		function IORegistryEntryFromPath( masterPort: mach_port_t; const path: io_string_t): io_registry_entry_t; cdecl; external;
780	788		function IORegistryEntryCreateCFProperty(entry: io_registry_entry_t; key: CFStringRef; allocator:CFAllocatorRef; options: IOOptionBits): CFTypeRef; cdecl; external;
781	789		function IOObjectRelease(entry: io_registry_entry_t): kern_return_t; cdecl; external;
782	790
783	791		function get_platform_uuid: string;
784	792		var
785	793		ioRegistryRoot :io_registry_entry_t;
786	794		uuidCf :CFStringRef;
787	795		l :integer;
788	796		begin
789	797		ioRegistryRoot := IORegistryEntryFromPath(kIOMasterPortDefault, 'IOService:/');
790	798		uuidCf := CFStringRef (IORegistryEntryCreateCFProperty(ioRegistryRoot, CFSTR(kIOPlatformUUIDKey), kCFAllocatorDefault, 0));
791	799		IOObjectRelease(ioRegistryRoot);
792	800		SetLength(Result, 1024);
793	801		CFStringGetCString(uuidCf, @Result[1], length(Result), kCFStringEncodingMacRoman);
794	802		CFRelease(uuidCf);
795	803		l:=StrLen(@Result[1]);
796	804		SetLength(Result, l);
797	805		end;
798	806
799	807		begin
800	808		WriteLn('Platform UUID: ', get_platform_uuid);
801	809		end.
802	810		```
803	811
804	812		## External links
805	813
806	814		- [Apple: SysCtl](https://developer.apple.com/documentation/installerjs/system/1812308-sysctl)
807	815		- [Apple: NSProcessinfo](https://developer.apple.com/documentation/foundation/nsprocessinfo)
808	816		- [Apple: Gestalt Manager](https://developer.apple.com/documentation/coreservices/carbon_core/gestalt_manager)
809	817		- [Apple: Introduction to I/O Kit Fundamentals](https://developer.apple.com/library/archive/documentation/DeviceDrivers/Conceptual/IOKitFundamentals/Introduction/Introduction.html)
810	818		- [Apple: IOKit framework](https://developer.apple.com/documentation/iokit)
811	819		- [Apple: DriverKit framework](https://developer.apple.com/documentation/driverkit)
812	820		- [Apple: Uniquely Identifying a Macintosh Computer](https://developer.apple.com/library/archive/technotes/tn1103/_index.html#//apple_ref/doc/uid/DTS10002943)
813	821
814	822		---
815	823		From the Free Pascal wiki, page "Accessing macOS System Information", as it stood on 2022-01-05 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history