PROFIL(2)

💖 PROFIL(2) 💖 — bestie edition, aka profil system call

okay so picture this: you're on a Debian system, it's December 1, 2017, and you wanna know what your program is actually doing with its life. enter profil(2), the system call manual page. it's giving main character energy for your program counter. let's go 🫶

---

✨ NAME ✨

profil — control process profiling 💅

---

📚 LIBRARY 📚

Standard C Library (libc, -lc) — yeah, it's in the regular libc, no special girlies needed 🎀

---

🌸 SYNOPSIS 🌸

#include <unistd.h>

int
profil(char *samples, size_t size, vm_offset_t offset, int scale);

---

🦋 DESCRIPTION 🦋

The profil() system call turns program counter profiling of the current process on or off. no cap. when profiling is on, every single profiling clock tick, the kernel goes and bumps an appropriate count in the samples buffer. and the frequency of that profiling clock? it's recorded in the header in the profiling output file. iykyk ✨

So the buffer samples contains size bytes and is split into a bunch of 16-bit bins. each bin is literally counting how many times the program counter was hanging out in a particular address range in the process when a profiling clock tick happened while profiling was enabled. like a little attendance sheet for addresses 📝

For a given program counter address, the number of the corresponding bin is given by this iconic relation:

[(pc - offset) / 2] * scale / 65536

The offset argument is the lowest address at which the kernel takes program counter samples. and the scale argument ranges from 1 to 65536, and you use it to change the span of the bins. so:

• a scale of 65536 maps each bin to 2 bytes of address range
• a scale of 32768 gives 4 bytes
• 16384 gives 8 bytes
• and so on, you get the vibe 💫

intermediate values give you approximate intermediate ranges. and a scale value of 0? that disables profiling. periodt.

---

🔥 RETURN VALUES 🔥

The profil() function returns the value 0 if successful 🎉 otherwise the value -1 is returned and the global variable errno is set to indicate the error. sad girl hours 😭

---

🎀 FILES 🎀

• /usr/lib/gcrt0.o — profiling C run-time startup file ⭐
• gmon.out — conventional name for profiling output file 🌈

---

💀 ERRORS 💀

The following error may be reported:

• [EFAULT] — the buffer samples contains an invalid address. not it. 🙈

---

👑 SEE ALSO 👑

• gprof(1) — go read that one too bestie, they're a package deal 🫶

---

🧚 HISTORY 🧚

The profil() function appeared in Version 6 AT&T UNIX. like, ancient. vintage. iconic. truly a legacy queen 💜

---

💅 BUGS 💅

ngl these are real, so listen up:

• This routine should be named profile(). the missing e? a crime. we've been carrying it for decades 😭
• The samples argument should really be a vector of type unsigned short. yes really.
• The format of the gmon.out file is undocumented. so like… good luck figuring it out yourself, bestie 💀

---

okay that's the whole page!! go profile something and slay ✨ this has been the PROFIL(2) System Calls Manual, from Debian, dated December 1, 2017 — mwah, take care of her, she's been around since Version 6 AT&T UNIX and she's still serving 🌸💖🎀