POSIXSHMCONTROL(1)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 posixshmcontrol(1) — the girlies' guide to POSIX shared memory 💖

ok so this is posixshmcontrol, straight out of the General Commands Manual, and bestie it is literally the tool for wrangling named POSIX shared memory segments. she's giving system-administrator realness and honestly? iconic. let's get into it 🫶

✨ NAME ✨

posixshmcontrol — control POSIX shared memory segments 💅

🌸 SYNOPSIS 🌸

posixshmcontrol create [-l pagesize] [-m mode] [path ...]
posixshmcontrol rm [path ...]
posixshmcontrol ls [-h] [-n] [-j jail]
posixshmcontrol dump [path ...]
posixshmcontrol stat [-h] [-n] [path ...]
posixshmcontrol truncate [-s length] [path ...]

🦋 DESCRIPTION 🦋

okay so posixshmcontrol manipulates the named POSIX shared memory segments. she's the one who lets you inspect existing segments, dump their metadata or their actual contents, and unlink them. main character energy fr.

Unlinking removes the name from the system — and then, when the last process unmaps the segment and closes the file descriptor pointing to the segment, the underlying memory gets freed. that's the whole life cycle, no cap 🌈

and here's a fun little detail: the number of hard links as displayed by the stat subcommand is equal to the number of references to the underlying VM object. it's almost always equal to the number of mappings +1, except for transient references. iykyk 🔥

the following subcommands are provided:

  • create — creates segments with the specified paths, if they do not already exist. the optional pagesize argument specifies the size of the virtual pages used to map the object with mmap(2). by default, the system page size is used — but on some platforms a larger page size can be specified 👀. heads up: the size of an object backed by large pages must be a multiple of the specified page size. the hw.pagesizes sysctl variable lists the available page sizes. the optional numerical mode argument specifies the initial access mode.
  • rm — unlinks the paths specified. bye bye bestie 💀
  • ls — lists all linked named shared memory segments visible to the caller. for each segment, the user and group owner, size, and path are displayed. the -j option limits the output to segments within the specified jail name or id.
  • dump — outputs raw bytes values from the segment to standard output. raw. unfiltered. 💅
  • stat — prints metadata for the specified path, in a format similar to the stat(1) utility.
  • truncate — changes the length of the segments. the argument to the -s option specifies the new length. the human-friendly 'k', 'm', 'g' suffixes can be used — see expand_number(3). if the option is not specified, the assumed length is zero.

🎀 OPTIONS 🎀

for some commands, the following options may be provided:

  • -h — if specified, requests human-readable display of size, see humanize_number(3). so like, cute numbers instead of a big scary blob of digits ✨
  • -n — prevents translation of owner and group into symbolic names using name-switch services. instead, the raw numeric values are printed. no names, just numbers, rawdogging it 🙈

🌟 EXIT STATUS 🌟

the posixshmcontrol utility exits 0 on success, and >0 if an error occurs. so 0 = slay, anything above = something went wrong, sadly 😭

💜 EXAMPLES 💜

  • to show content of the shared memory segment with the path /1, use the command
posixshmcontrol dump /1 | hexdump -C
  • to create a segment with the path /2 and then enlarge it to 1M, use the sequence of commands
posixshmcontrol create /2
posixshmcontrol truncate -s 1m /2

🍓 SEE ALSO 🍓

hexdump(1), stat(1), ftruncate(2), mmap(2), read(2), shm_open(2), shm_unlink(2), stat(2), expand_number(3), humanize_number(3), shm_create_largepage(3), sysctl(3)

go read them. do it for the plot 🧚

⭐ HISTORY ⭐

the posixshmcontrol command appeared in FreeBSD 12.1. vintage but make it fresh 👑

👑 AUTHORS 👑

the posixshmcontrol command and this manual page were written by Konstantin Belousov <kib@freebsd.org> under sponsorship from The FreeBSD Foundation. king behavior fr fr 🫶

alright bestie that's the whole page 💖 this Debian build is dated May 25, 2023, and it shipped under the POSIXSHMCONTROL(1) banner. now go dump some segments, you absolute icon 🌸💅✨

📦 where this page comes from