Accessing FreeBSD 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		[Sysctl](https://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=3) provides an interface that allows you to read and, with appropriate privileges, set many kernel attributes in FreeBSD (the BSDs, macOS and Linux). 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).
2	2
3	3		The '/usr/local/share/fpcsrc/rtl/freebsd/sysctlh.inc' source file is a partial translation of the FreeBSD '/usr/include/sys/sysctl.h' file. For details of the sysctls available, start a console or X11 xterm and type 'man sysctl'. Typing 'sysctl -a \\| more' will list all the available sysctls and their values.
4	4
5	5		## FPsysctl()
6	6
7	7		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:
8	8
9	9		``` pascal
10	10		function FPsysctl (Name: pchar; namelen:cuint; oldp:pointer;oldlenp:psize_t; newp:pointer;newlen:size_t):cint; cdecl; external name 'sysctl';
11	11		```
12	12
13	13		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.
14	14
15	15		namelen -- the length of the array of integers in name.
16	16
17	17		Note: if the old attribute value is not required, the next two variables can be set to Nil and 0.
18	18
19	19		oldp -- a pointer to the buffer into which the value is copied.
20	20
21	21		oldlenp -- the size of the oldp buffer.
22	22
23	23		Note: if the new attribute value is not being set, the next two variables should be set to Nil and 0.
24	24
25	25		newp -- a pointer to the buffer containing the new value to be set.
26	26
27	27		newlen -- the size of the newp buffer.
28	28
29	29		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:
30	30
31		-	~~` -------------------------------------------------------------------------------`\~~
32		-	~~` Name Value Next level names Description`\~~
33		-	~~` are found in`\~~
34		-	~~` -------------------------------------------------------------------------------`\~~
35		-	~~` #define CTL_KERN 1 sys/sysctl.h /* High kernel limits */`\~~
36		-	~~` #define CTL_VM 2 vm/vm_param.h /* Virtual memory */`\~~
37		-	~~` #define CTL_VFS 3 sys/mount.h /* File system */`\~~
38		-	~~` #define CTL_NET 4 sys/socket.h /* Networking */`\~~
39		-	~~` #define CTL_DEBUG 5 sys/sysctl.h /* Debugging */`\~~
40		-	~~` #define CTL_HW 6 sys/sysctl.h /* Generic CPU, I/O */`\~~
41		-	~~` #define CTL_MACHDEP 7 sys/sysctl.h /* Machine dependent */`\~~
42		-	~~` #define CTL_USER 8 sys/sysctl.h /* User-level */`\~~
43		-	~~` #define CTL_P1003_1B 9 sys/sysctl.h /* POSIX 1003.1B */`\~~
44		-	~~` -------------------------------------------------------------------------------`~~
	31	+	```
	32	+	-------------------------------------------------------------------------------
	33	+	Name Value Next level names Description
	34	+	are found in
	35	+	-------------------------------------------------------------------------------
	36	+	#define CTL_KERN 1 sys/sysctl.h /* High kernel limits */
	37	+	#define CTL_VM 2 vm/vm_param.h /* Virtual memory */
	38	+	#define CTL_VFS 3 sys/mount.h /* File system */
	39	+	#define CTL_NET 4 sys/socket.h /* Networking */
	40	+	#define CTL_DEBUG 5 sys/sysctl.h /* Debugging */
	41	+	#define CTL_HW 6 sys/sysctl.h /* Generic CPU, I/O */
	42	+	#define CTL_MACHDEP 7 sys/sysctl.h /* Machine dependent */
	43	+	#define CTL_USER 8 sys/sysctl.h /* User-level */
	44	+	#define CTL_P1003_1B 9 sys/sysctl.h /* POSIX 1003.1B */
	45	+	-------------------------------------------------------------------------------
	46	+	```
45	47
46	48		Let's look at CTL_HW level of information. The subsequent elements are found in the system sysctl.h file and are:
47	49
48		-	~~` ------------------------------------------------------------------------------- `\~~
49		-	~~` Name Value Description`\~~
50		-	~~` ------------------------------------------------------------------------------- `\~~
51		-	~~` #define HW_MACHINE 1 /* string: machine class */`\~~
52		-	~~` #define HW_MODEL 2 /* string: specific machine model */`\~~
53		-	~~` #define HW_NCPU 3 /* int: number of cpus */`\~~
54		-	~~` #define HW_BYTEORDER 4 /* int: byte order (4321 or 1234) */`\~~
55		-	~~` #define HW_PHYSMEM 5 /* int: total memory in bytes */`\~~
56		-	~~` #define HW_USERMEM 6 /* int: memory in bytes not wired */`\~~
57		-	~~` #define HW_PAGESIZE 7 /* int: software page size */`\~~
58		-	~~` #define HW_DISKNAMES 8 /* strings: disk drive names */`\~~
59		-	~~` #define HW_DISKSTATS 9 /* struct: diskstats[] */`\~~
60		-	~~` #define HW_FLOATINGPT 10 /* int: has HW floating point? */`\~~
61		-	~~` #define HW_MACHINE_ARCH 11 /* string: machine architecture */`\~~
62		-	~~` #define HW_REALMEM 12 /* int: 'real' memory */`\~~
63		-	~~` -------------------------------------------------------------------------------`~~
	50	+	```
	51	+	-------------------------------------------------------------------------------
	52	+	Name Value Description
	53	+	-------------------------------------------------------------------------------
	54	+	#define HW_MACHINE 1 /* string: machine class */
	55	+	#define HW_MODEL 2 /* string: specific machine model */
	56	+	#define HW_NCPU 3 /* int: number of cpus */
	57	+	#define HW_BYTEORDER 4 /* int: byte order (4321 or 1234) */
	58	+	#define HW_PHYSMEM 5 /* int: total memory in bytes */
	59	+	#define HW_USERMEM 6 /* int: memory in bytes not wired */
	60	+	#define HW_PAGESIZE 7 /* int: software page size */
	61	+	#define HW_DISKNAMES 8 /* strings: disk drive names */
	62	+	#define HW_DISKSTATS 9 /* struct: diskstats[] */
	63	+	#define HW_FLOATINGPT 10 /* int: has HW floating point? */
	64	+	#define HW_MACHINE_ARCH 11 /* string: machine architecture */
	65	+	#define HW_REALMEM 12 /* int: 'real' memory */
	66	+	-------------------------------------------------------------------------------
	67	+	```
64	68
65	69		### Example: Number of CPUs
66	70
67	71		Armed with this information, we can now find out the number of CPUs:
68	72
69	73		``` pascal
70	74		{$mode objfpc}
71	75		...
72	76
73	77		Uses
74	78		unix,
75	79		sysctl, // fpSysCtl
76	80		sysutils; // RaiseLastOSError
77	81		...
78	82
79	83		function NumberOfCPU: Integer;
80	84
81	85		var
82	86		mib: array[0..1] of Integer;
83	87		status : Integer;
84	88		len : size_t;
85	89
86	90		begin
87	91		mib[0] := CTL_HW;
88	92		mib[1] := HW_NCPU;
89	93
90	94		len := SizeOf(Result);
91	95		status := fpSysCtl(PChar(@mib), Length(mib), @Result, @len, Nil, 0);
92	96		if status <> 0 then RaiseLastOSError;
93	97		end;
94	98		```
95	99
96	100		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).
97	101
98	102		There is a possible issue with the above because if you have, for example, a multi-core CPU. One guess. Yes, it will return the total number of cores and, if your microprocessor supports hyperthreading, the number of cores plus the number of hardware threads -- not the number of discrete CPUs. This may not matter depending on your use case, but you should be aware of it.
99	103
100	104		### Example: CPU model
101	105
102	106		Before we move on to look at a second function 'FPsysctlbyname', let's look at retrieving a string with FPsysctl() which is a little different than retrieving an integer.
103	107
104	108		``` pascal
105	109		{$mode objfpc}
106	110		...
107	111
108	112		Uses
109	113		unix,
110	114		sysctl, // fpSysCtl
111	115		sysutils; // RaiseLastOSError
112	116		...
113	117
114	118		function HWmodel : AnsiString;
115	119
116	120		var
117	121		mib : array[0..1] of Integer;
118	122		status : Integer;
119	123		len : size_t;
120	124		p : PChar;
121	125
122	126		begin
123	127		mib[0] := CTL_HW;
124	128		mib[1] := HW_MODEL;
125	129
126	130		status := fpSysCtl(PChar(@mib), Length(mib), Nil, @len, Nil, 0);
127	131		if status <> 0 then RaiseLastOSError;
128	132
129	133		GetMem(p, len);
130	134
131	135		try
132	136		status := fpSysCtl(PChar(@mib), Length(mib), p, @len, Nil, 0);
133	137		if status <> 0 then RaiseLastOSError;
134	138		Result := p;
135	139		finally
136	140		FreeMem(p);
137	141		end;
138	142		end;
139	143		```
140	144
141	145		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 to be returned, and the second to actually retrieve the string value into that buffer. On my FreeBSD Apple Mac mini computer this returns the string "Intel(R) Core(TM) i7-8700B CPU @ 3.20GHz".
142	146
143	147		### Example: Clock info
144	148
145	149		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).
146	150
147	151		``` pascal
148	152		{$mode objfpc}
149	153		...
150	154
151	155		Uses
152	156		unix,
153	157		sysctl, // fpSysCtl
154	158		sysutils; // RaiseLastOSError
155	159		...
156	160
157	161		function GetClockInfo: String;
158	162
159	163		type
160	164		clockinfo = record
161	165		hz : Integer; // clock frequency
162	166		tick : Integer; // ms per Hz tick
163	167		spare : Integer; // unused
164	168		stathz : Integer; // statistics clock frequency
165	169		profhz : Integer; // profiling clock frequency
166	170		end;
167	171
168	172		var
169	173		mib : array[0..1] of Integer;
170	174		status : Integer;
171	175		len : size_t;
172	176		clock : clockinfo;
173	177		begin
174	178		mib[0] := CTL_KERN;
175	179		mib[1] := KERN_CLOCKRATE;
176	180		clock := Default(clockinfo);
177	181
178	182		FillChar(clock, sizeof(clock), 0);
179	183		len := sizeof(clock);
180	184
181	185		status := fpSysCtl(@mib, Length(mib), @clock, @len, Nil, 0);
182	186		if status <> 0 then RaiseLastOSError;
183	187
184	188		Result := 'Clock freq: ' + IntToStr(clock.hz) + 'Hz' + LineEnding
185	189		+ 'Ms per Hz tick: ' + IntToStr(clock.tick) + LineEnding
186	190		+ 'Profiling clock freq: ' + IntToStr(clock.profhz) + ' Hz'
187	191		+ LineEnding;
188	192		end;
189	193		```
190	194
191	195		On my computer this returned:
192	196
193		-	~~`Clock freq: 100Hz`\~~
194		-	~~`Ms per Hz tick: 10000`\~~
195		-	~~`Profiling clock freq: 8128 Hz`~~
	197	+	```
	198	+	Clock freq: 100Hz
	199	+	Ms per Hz tick: 10000
	200	+	Profiling clock freq: 8128 Hz
	201	+	```
196	202
197	203		The clockinfo record was pretty easily translated into a Pascal record from the C structure found in the system time.h file:
198	204
199	205		``` c
200	206		struct clockinfo {
201	207		int hz; /* clock frequency */
202	208		int tick; /* micro-seconds per hz tick */
203	209		int spare;
204	210		int stathz; /* statistics clock frequency */
205	211		int profhz; /* profiling clock frequency */
206	212		};
207	213		```
208	214
209	215		### Example: Real executable path
210	216
211	217		First some background. Many Pascal programmers are in love with the `ExtractFilePath(ParamStr(0))` function to find the path of an executable. Just don't do it! Paramstr(0) must only be used on DOS and Windows (and maybe OS/2). On all other platforms the results are unpredictable and it will not work as you expect (in the best case it will never work; in the worst case it will only fail under certain circumstances, resulting in hard-to-find bugs). For the gory details, see [this thread's posts by Jonas](https://lists.freepascal.org/pipermail/fpc-pascal/2009-February/020211.html).
212	218
213	219		Instead, sysctl to the rescue.
214	220
215	221		``` pascal
216	222		{$mode objfpc}
217	223
218	224		Uses
219	225		unix,
220	226		sysctl, // fpSysCtl
221	227		sysutils; // RaiseLastOSError
222	228
223	229		function realPath: string;
224	230
225	231		var
226	232		mib: array[0..3] of Integer;
227	233		status : Integer;
228	234		len : size_t;
229	235
230	236		begin
231	237		mib[0] := CTL_KERN;
232	238		mib[1] := KERN_PROC;
233	239		mib[2] := KERN_PROC_PATHNAME;
234	240		mib[3] := -1;
235	241
236	242		len := SizeOf(Result);
237	243		status := fpSysCtl(PChar(@mib), Length(mib), @Result, @len, Nil, 0);
238	244		if status <> 0 then RaiseLastOSError;
239	245		end;
240	246
241	247		begin
242	248		WriteLn(realPath);
243	249		end.
244	250		```
245	251
246	252		Finally, yes, it is time to move on to the FPsysctlbyname() function.
247	253
248	254		## FPsysctlbyname
249	255
250	256		The FPsysctlbyname function is defined in '/usr/local/share/fpcsrc/rtl/bsd/sysctl.pp' as:
251	257
252	258		``` pascal
253	259		function FPsysctlbyname (Name: pchar; oldp:pointer;oldlenp:psize_t; newp:pointer;newlen:size_t):cint; cdecl; external name 'sysctlbyname';
254	260		```
255	261
256	262		There. Not really very different from the FPsysctl() function. Is that a sigh of relief?
257	263
258	264		### Example: Number of CPU cores
259	265
260	266		So let's look at finally retrieving the number of CPU cores.
261	267
262	268		``` pascal
263	269		{$mode objfpc}
264	270		...
265	271
266	272		Uses
267	273		unix,
268	274		sysctl, // fpSysCtlByName
269	275		sysutils; // RaiseLastOSError
270	276		...
271	277
272	278		function NumberOfCPU: Integer;
273	279
274	280		var
275	281		status : Integer;
276	282		len : size_t;
277	283
278	284		begin
279	285		len := SizeOf(Result);
280	286
281	287		status := fpSysCtlByName('hw.ncpu', @Result, @len, Nil, 0);
282	288		if status <> 0 then RaiseLastOSError;
283	289		end;
284	290		```
285	291
286	292		On my FreeBSD computer this returns the number of cores: 6. Where do you find the special incantation 'hw.ncpu' ? In the manual pages for the sysctl command (man 3 sysctl \[Library functions section\] and man 8 sysctl \[System manager's section\]). Here's a brief excerpt of the hardware selectors:
287	293
288		-	~~` Parameters that are byte counts are 64 bit numbers. All other byte parameters are 32 bit numbers.`~~
	294	+	```
	295	+	Parameters that are byte counts are 64 bit numbers. All other byte parameters are 32 bit numbers.
	296	+	```
289	297
290		-	~~` --------------------------------------------------------------------------------------------`\~~
291		-	~~` Descriptor Type Changeable Description`\~~
292		-	~~` --------------------------------------------------------------------------------------------`\~~
293		-	~~` hw.machine string no Machine class`\~~
294		-	~~` hw.model string no Machine model`\~~
295		-	~~` hw.ncpu integer no Number of cpus`\~~
296		-	~~` hw.byteorder integer no Byteorder (4321 or 1234)`\~~
297		-	~~` hw.physmem integer no Bytes of physical memory`\~~
298		-	~~` hw.usermem integer no Bytes of non-kernel memory`\~~
299		-	~~` hw.pagesize integer no Software page size`\~~
300		-	~~` hw.floatingpoint integer no Non-zero if hardware floating point`\~~
301		-	~~` hw.machine_arch string no Machine dependent architecture`\~~
302		-	~~` hw.realmem integer no Bytes of real memory`\~~
303		-	~~` --------------------------------------------------------------------------------------------`~~
	298	+	``` pascal
	299	+	--------------------------------------------------------------------------------------------
	300	+	Descriptor Type Changeable Description
	301	+	--------------------------------------------------------------------------------------------
	302	+	hw.machine string no Machine class
	303	+	hw.model string no Machine model
	304	+	hw.ncpu integer no Number of cpus
	305	+	hw.byteorder integer no Byteorder (4321 or 1234)
	306	+	hw.physmem integer no Bytes of physical memory
	307	+	hw.usermem integer no Bytes of non-kernel memory
	308	+	hw.pagesize integer no Software page size
	309	+	hw.floatingpoint integer no Non-zero if hardware floating point
	310	+	hw.machine_arch string no Machine dependent architecture
	311	+	hw.realmem integer no Bytes of real memory
	312	+	--------------------------------------------------------------------------------------------
	313	+	```
304	314
305	315		If you prefer, you can also use the sysctl command line utility in a console or X11 xterm to list all the hw selectors with "sysctl hw.".
306	316
307	317		### Example: CPU architecture
308	318
309	319		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!
310	320
311	321		``` pascal
312	322		{$mode objfpc}
313	323		...
314	324
315	325		Uses
316	326		unix,
317	327		sysctl, // fpSysCtlByName
318	328		sysutils; // RaiseLastOSError
319	329		...
320	330
321	331		function GetCPUarchitecture: AnsiString;
322	332
323	333		var
324	334		status : Integer;
325	335		len : size_t;
326	336		p : PChar;
327	337		begin
328	338		status := fpSysCtlByName('hw.machine_arch', Nil, @len, Nil, 0);
329	339		if status <> 0 then RaiseLastOSError;
330	340
331	341		GetMem(p, len);
332	342
333	343		try
334	344		status := fpSysCtlByName('hw.machine_arch', p, @len, Nil, 0);
335	345		if status <> 0 then RaiseLastOSError;
336	346		Result := p;
337	347		finally
338	348		FreeMem(p);
339	349		end;
340	350		end;
341	351		```
342	352
343	353		On my FreeBSD computer, this returns the string: amd64.
344	354
345	355		### Example: CPU clock speed
346	356
347	357		``` pascal
348	358		{$mode objfpc}
349	359		...
350	360
351	361		Uses
352	362		unix,
353	363		sysctl, // fpSysCtlByName
354	364		sysutils; // RaiseLastOSError
355	365		...
356	366
357	367		function GetCPUClockRate: integer;
358	368
359	369		var
360	370		status : Integer;
361	371		len : size_t;
362	372
363	373		begin
364	374		len := SizeOf(Result);
365	375		status := fpSysCtlByName('hw.clockrate', @Result, @len, Nil, 0);
366	376		if status <> 0 then RaiseLastOSError;
367	377		end;
368	378		```
369	379
370	380		For an Intel(R) Core(TM) i7-2620M CPU @ 2.70GHz, this returns 2.693 (GHz).
371	381
372	382		## Last words
373	383
374	384		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.
375	385
376	386		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 and the manual page for sysctl (man 3 sysctl).
377	387
378	388		## External links
379	389
380	390		- [sysctlbyname improved](https://gitlab.com/alfix/sysctlbyname-improved) - A new sysctl internal object to convert a sysctl name to the corresponding OID and to improve sysctlbyname(3).
381	391
382	392		---
383	393		From the Free Pascal wiki, page "Accessing FreeBSD System Information", as it stood on 2021-03-09 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