Accessing FreeBSD System Information: what changed

Revision 2 to 3. 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		-	~~```~~
	31	+	```text
32	32		-------------------------------------------------------------------------------
33	33		Name Value Next level names Description
34	34		are found in
35	35		-------------------------------------------------------------------------------
36	36		#define CTL_KERN 1 sys/sysctl.h /* High kernel limits */
37	37		#define CTL_VM 2 vm/vm_param.h /* Virtual memory */
38	38		#define CTL_VFS 3 sys/mount.h /* File system */
39	39		#define CTL_NET 4 sys/socket.h /* Networking */
40	40		#define CTL_DEBUG 5 sys/sysctl.h /* Debugging */
41	41		#define CTL_HW 6 sys/sysctl.h /* Generic CPU, I/O */
42	42		#define CTL_MACHDEP 7 sys/sysctl.h /* Machine dependent */
43	43		#define CTL_USER 8 sys/sysctl.h /* User-level */
44	44		#define CTL_P1003_1B 9 sys/sysctl.h /* POSIX 1003.1B */
45	45		-------------------------------------------------------------------------------
46	46		```
47	47
48	48		Let's look at CTL_HW level of information. The subsequent elements are found in the system sysctl.h file and are:
49	49
50		-	~~```~~
	50	+	```text
51	51		-------------------------------------------------------------------------------
52	52		Name Value Description
53	53		-------------------------------------------------------------------------------
54	54		#define HW_MACHINE 1 /* string: machine class */
55	55		#define HW_MODEL 2 /* string: specific machine model */
56	56		#define HW_NCPU 3 /* int: number of cpus */
57	57		#define HW_BYTEORDER 4 /* int: byte order (4321 or 1234) */
58	58		#define HW_PHYSMEM 5 /* int: total memory in bytes */
59	59		#define HW_USERMEM 6 /* int: memory in bytes not wired */
60	60		#define HW_PAGESIZE 7 /* int: software page size */
61	61		#define HW_DISKNAMES 8 /* strings: disk drive names */
62	62		#define HW_DISKSTATS 9 /* struct: diskstats[] */
63	63		#define HW_FLOATINGPT 10 /* int: has HW floating point? */
64	64		#define HW_MACHINE_ARCH 11 /* string: machine architecture */
65	65		#define HW_REALMEM 12 /* int: 'real' memory */
66	66		-------------------------------------------------------------------------------
67	67		```
68	68
69	69		### Example: Number of CPUs
70	70
71	71		Armed with this information, we can now find out the number of CPUs:
72	72
73	73		``` pascal
74	74		{$mode objfpc}
75	75		...
76	76
77	77		Uses
78	78		unix,
79	79		sysctl, // fpSysCtl
80	80		sysutils; // RaiseLastOSError
81	81		...
82	82
83	83		function NumberOfCPU: Integer;
84	84
85	85		var
86	86		mib: array[0..1] of Integer;
87	87		status : Integer;
88	88		len : size_t;
89	89
90	90		begin
91	91		mib[0] := CTL_HW;
92	92		mib[1] := HW_NCPU;
93	93
94	94		len := SizeOf(Result);
95	95		status := fpSysCtl(PChar(@mib), Length(mib), @Result, @len, Nil, 0);
96	96		if status <> 0 then RaiseLastOSError;
97	97		end;
98	98		```
99	99
100	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).
101	101
102	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.
103	103
104	104		### Example: CPU model
105	105
106	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.
107	107
108	108		``` pascal
109	109		{$mode objfpc}
110	110		...
111	111
112	112		Uses
113	113		unix,
114	114		sysctl, // fpSysCtl
115	115		sysutils; // RaiseLastOSError
116	116		...
117	117
118	118		function HWmodel : AnsiString;
119	119
120	120		var
121	121		mib : array[0..1] of Integer;
122	122		status : Integer;
123	123		len : size_t;
124	124		p : PChar;
125	125
126	126		begin
127	127		mib[0] := CTL_HW;
128	128		mib[1] := HW_MODEL;
129	129
130	130		status := fpSysCtl(PChar(@mib), Length(mib), Nil, @len, Nil, 0);
131	131		if status <> 0 then RaiseLastOSError;
132	132
133	133		GetMem(p, len);
134	134
135	135		try
136	136		status := fpSysCtl(PChar(@mib), Length(mib), p, @len, Nil, 0);
137	137		if status <> 0 then RaiseLastOSError;
138	138		Result := p;
139	139		finally
140	140		FreeMem(p);
141	141		end;
142	142		end;
143	143		```
144	144
145	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".
146	146
147	147		### Example: Clock info
148	148
149	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).
150	150
151	151		``` pascal
152	152		{$mode objfpc}
153	153		...
154	154
155	155		Uses
156	156		unix,
157	157		sysctl, // fpSysCtl
158	158		sysutils; // RaiseLastOSError
159	159		...
160	160
161	161		function GetClockInfo: String;
162	162
163	163		type
164	164		clockinfo = record
165	165		hz : Integer; // clock frequency
166	166		tick : Integer; // ms per Hz tick
167	167		spare : Integer; // unused
168	168		stathz : Integer; // statistics clock frequency
169	169		profhz : Integer; // profiling clock frequency
170	170		end;
171	171
172	172		var
173	173		mib : array[0..1] of Integer;
174	174		status : Integer;
175	175		len : size_t;
176	176		clock : clockinfo;
177	177		begin
178	178		mib[0] := CTL_KERN;
179	179		mib[1] := KERN_CLOCKRATE;
180	180		clock := Default(clockinfo);
181	181
182	182		FillChar(clock, sizeof(clock), 0);
183	183		len := sizeof(clock);
184	184
185	185		status := fpSysCtl(@mib, Length(mib), @clock, @len, Nil, 0);
186	186		if status <> 0 then RaiseLastOSError;
187	187
188	188		Result := 'Clock freq: ' + IntToStr(clock.hz) + 'Hz' + LineEnding
189	189		+ 'Ms per Hz tick: ' + IntToStr(clock.tick) + LineEnding
190	190		+ 'Profiling clock freq: ' + IntToStr(clock.profhz) + ' Hz'
191	191		+ LineEnding;
192	192		end;
193	193		```
194	194
195	195		On my computer this returned:
196	196
197		-	~~```~~
	197	+	```text
198	198		Clock freq: 100Hz
199	199		Ms per Hz tick: 10000
200	200		Profiling clock freq: 8128 Hz
201	201		```
202	202
203	203		The clockinfo record was pretty easily translated into a Pascal record from the C structure found in the system time.h file:
204	204
205	205		``` c
206	206		struct clockinfo {
207	207		int hz; /* clock frequency */
208	208		int tick; /* micro-seconds per hz tick */
209	209		int spare;
210	210		int stathz; /* statistics clock frequency */
211	211		int profhz; /* profiling clock frequency */
212	212		};
213	213		```
214	214
215	215		### Example: Real executable path
216	216
217	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).
218	218
219	219		Instead, sysctl to the rescue.
220	220
221	221		``` pascal
222	222		{$mode objfpc}
223	223
224	224		Uses
225	225		unix,
226	226		sysctl, // fpSysCtl
227	227		sysutils; // RaiseLastOSError
228	228
229	229		function realPath: string;
230	230
231	231		var
232	232		mib: array[0..3] of Integer;
233	233		status : Integer;
234	234		len : size_t;
235	235
236	236		begin
237	237		mib[0] := CTL_KERN;
238	238		mib[1] := KERN_PROC;
239	239		mib[2] := KERN_PROC_PATHNAME;
240	240		mib[3] := -1;
241	241
242	242		len := SizeOf(Result);
243	243		status := fpSysCtl(PChar(@mib), Length(mib), @Result, @len, Nil, 0);
244	244		if status <> 0 then RaiseLastOSError;
245	245		end;
246	246
247	247		begin
248	248		WriteLn(realPath);
249	249		end.
250	250		```
251	251
252	252		Finally, yes, it is time to move on to the FPsysctlbyname() function.
253	253
254	254		## FPsysctlbyname
255	255
256	256		The FPsysctlbyname function is defined in '/usr/local/share/fpcsrc/rtl/bsd/sysctl.pp' as:
257	257
258	258		``` pascal
259	259		function FPsysctlbyname (Name: pchar; oldp:pointer;oldlenp:psize_t; newp:pointer;newlen:size_t):cint; cdecl; external name 'sysctlbyname';
260	260		```
261	261
262	262		There. Not really very different from the FPsysctl() function. Is that a sigh of relief?
263	263
264	264		### Example: Number of CPU cores
265	265
266	266		So let's look at finally retrieving the number of CPU cores.
267	267
268	268		``` pascal
269	269		{$mode objfpc}
270	270		...
271	271
272	272		Uses
273	273		unix,
274	274		sysctl, // fpSysCtlByName
275	275		sysutils; // RaiseLastOSError
276	276		...
277	277
278	278		function NumberOfCPU: Integer;
279	279
280	280		var
281	281		status : Integer;
282	282		len : size_t;
283	283
284	284		begin
285	285		len := SizeOf(Result);
286	286
287	287		status := fpSysCtlByName('hw.ncpu', @Result, @len, Nil, 0);
288	288		if status <> 0 then RaiseLastOSError;
289	289		end;
290	290		```
291	291
292	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:
293	293
294		-	~~```~~
	294	+	```text
295	295		Parameters that are byte counts are 64 bit numbers. All other byte parameters are 32 bit numbers.
296	296		```
297	297
298	298		``` pascal
299	299		--------------------------------------------------------------------------------------------
300	300		Descriptor Type Changeable Description
301	301		--------------------------------------------------------------------------------------------
302	302		hw.machine string no Machine class
303	303		hw.model string no Machine model
304	304		hw.ncpu integer no Number of cpus
305	305		hw.byteorder integer no Byteorder (4321 or 1234)
306	306		hw.physmem integer no Bytes of physical memory
307	307		hw.usermem integer no Bytes of non-kernel memory
308	308		hw.pagesize integer no Software page size
309	309		hw.floatingpoint integer no Non-zero if hardware floating point
310	310		hw.machine_arch string no Machine dependent architecture
311	311		hw.realmem integer no Bytes of real memory
312	312		--------------------------------------------------------------------------------------------
313	313		```
314	314
315	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.".
316	316
317	317		### Example: CPU architecture
318	318
319	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!
320	320
321	321		``` pascal
322	322		{$mode objfpc}
323	323		...
324	324
325	325		Uses
326	326		unix,
327	327		sysctl, // fpSysCtlByName
328	328		sysutils; // RaiseLastOSError
329	329		...
330	330
331	331		function GetCPUarchitecture: AnsiString;
332	332
333	333		var
334	334		status : Integer;
335	335		len : size_t;
336	336		p : PChar;
337	337		begin
338	338		status := fpSysCtlByName('hw.machine_arch', Nil, @len, Nil, 0);
339	339		if status <> 0 then RaiseLastOSError;
340	340
341	341		GetMem(p, len);
342	342
343	343		try
344	344		status := fpSysCtlByName('hw.machine_arch', p, @len, Nil, 0);
345	345		if status <> 0 then RaiseLastOSError;
346	346		Result := p;
347	347		finally
348	348		FreeMem(p);
349	349		end;
350	350		end;
351	351		```
352	352
353	353		On my FreeBSD computer, this returns the string: amd64.
354	354
355	355		### Example: CPU clock speed
356	356
357	357		``` pascal
358	358		{$mode objfpc}
359	359		...
360	360
361	361		Uses
362	362		unix,
363	363		sysctl, // fpSysCtlByName
364	364		sysutils; // RaiseLastOSError
365	365		...
366	366
367	367		function GetCPUClockRate: integer;
368	368
369	369		var
370	370		status : Integer;
371	371		len : size_t;
372	372
373	373		begin
374	374		len := SizeOf(Result);
375	375		status := fpSysCtlByName('hw.clockrate', @Result, @len, Nil, 0);
376	376		if status <> 0 then RaiseLastOSError;
377	377		end;
378	378		```
379	379
380	380		For an Intel(R) Core(TM) i7-2620M CPU @ 2.70GHz, this returns 2.693 (GHz).
381	381
382	382		## Last words
383	383
384	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.
385	385
386	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).
387	387
388	388		## External links
389	389
390	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).
391	391
392	392		---
393	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