usr.bin/posixshmcontrol/posixshmcontrol.1

   1 .\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
   2 .\"
   3 .\" This documentation was written by
   4 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd May 25, 2023
  29 .Dt POSIXSHMCONTROL 1
  30 .Os
  31 .Sh NAME
  32 .Nm posixshmcontrol
  33 .Nd Control POSIX shared memory segments
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Ar create
  37 .Op Fl l Ar pagesize
  38 .Op Fl m Ar mode
  39 .Op Pa path \&...
  40 .Nm
  41 .Ar rm
  42 .Op Pa path \&...
  43 .Nm
  44 .Ar ls
  45 .Op Fl h
  46 .Op Fl n
  47 .Op Fl j Ar jail
  48 .Nm
  49 .Ar dump
  50 .Op Pa path \&...
  51 .Nm
  52 .Ar stat
  53 .Op Fl h
  54 .Op Fl n
  55 .Op Pa path \&...
  56 .Nm
  57 .Ar truncate
  58 .Op Fl s Ar length
  59 .Op Pa path \&...
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 command manipulates the named POSIX shared memory segments.
  64 It allows inspecting existing segments, dumping their metadata or contents,
  65 and unlinking them.
  66 .Pp
  67 Unlinking removes the name from the system and, when the last process
  68 unmaps the segment and closes file descriptor pointing to the segment,
  69 frees underlying memory.
  70 .Pp
  71 The number of hard links as displayed by the
  72 .Ic stat
  73 subcommand, is equal to the number of references to the underlying VM
  74 object.
  75 It is almost always equal to the number of mappings +1, except
  76 for transient references.
  77 .Pp
  78 The following subcommands are provided:
  79 .Bl -tag -width truncate
  80 .It Ic create
  81 Create segments with the specified paths, if they do not already exist.
  82 .Pp
  83 The optional
  84 .Ar pagesize
  85 argument specifies the size of the virtual pages used to map the
  86 object with
  87 .Xr mmap 2 .
  88 By default, the system page size is used, but on some platforms a
  89 larger page size can be specified.
  90 The size of an object backed by large pages must be a multiple of the
  91 specified page size.
  92 The
  93 .Va hw.pagesizes
  94 sysctl variable lists the available page sizes.
  95 .Pp
  96 The optional numerical
  97 .Ar mode
  98 argument specifies the initial access mode.
  99 .It Ic rm
 100 Unlink the paths specified.
 101 .It Ic ls
 102 List all linked named shared memory segments visible to the caller.
 103 For each segment, the user and group owner, size, and path are displayed.
 104 The
 105 .Fl j
 106 option limits the output to segments within the specified
 107 .Ar jail
 108 name or id.
 109 .It Ic dump
 110 Output raw bytes values from the segment to standard output.
 111 .It Ic stat
 112 Print metadata for the specified path, in the format similar to the
 113 .Xr stat 1
 114 utility.
 115 .It Ic truncate
 116 Change the length of the segments.
 117 Argument to the
 118 .Fl s
 119 option specifies new length.
 120 The human-friendly 'k', 'm', 'g' suffixes can be used, see
 121 .Xr expand_number 3 .
 122 If the option is not specified, assumed length is zero.
 123 .El
 124 .Pp
 125 For some commands, the following options may be provided:
 126 .Bl -tag -width XXX
 127 .It Fl h
 128 If specified, requests human-readable display of size, see
 129 .Xr humanize_number 3 .
 130 .It Fl n
 131 Prevent translation of owner and group into symbolic names
 132 using name-switch services, instead the raw numeric values are printed.
 133 .El
 134 .Sh EXIT STATUS
 135 .Ex -std
 136 .Sh EXAMPLES
 137 .Bl -bullet
 138 .It
 139 To show content of the shared memory segment with the path
 140 .Pa /1 ,
 141 use the command
 142 .Dl "posixshmcontrol dump /1 | hexdump -C"
 143 .It
 144 To create a segment with the path
 145 .Pa /2
 146 and then enlarge it to 1M, use the sequence of commands
 147 .Dl "posixshmcontrol create /2"
 148 .Dl "posixshmcontrol truncate -s 1m /2"
 149 .El
 150 .Sh SEE ALSO
 151 .Xr hexdump 1 ,
 152 .Xr stat 1 ,
 153 .Xr ftruncate 2 ,
 154 .Xr mmap 2 ,
 155 .Xr read 2 ,
 156 .Xr shm_open 2 ,
 157 .Xr shm_unlink 2 ,
 158 .Xr stat 2 ,
 159 .Xr expand_number 3 ,
 160 .Xr humanize_number 3 ,
 161 .Xr shm_create_largepage 3 ,
 162 .Xr sysctl 3
 163 .Sh HISTORY
 164 The
 165 .Nm
 166 command appeared in
 167 .Fx 12.1 .
 168 .Sh AUTHORS
 169 The
 170 .Nm
 171 command and this manual page were written by
 172 .An Konstantin Belousov Aq Mt kib@freebsd.org
 173 under sponsorship from The
 174 .Fx
 175 Foundation.