Changeset View
Changeset View
Standalone View
Standalone View
head/usr.bin/posixshmcontrol/posixshmcontrol.1
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" Copyright (c) 2019 The FreeBSD Foundation, Inc. | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" This documentation was written by | |||||
.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship | |||||
.\" from the FreeBSD Foundation. | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND | |||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE | |||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||
.\" SUCH DAMAGE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd May 27, 2019 | |||||
.Dt POSIXSHMCONTROL 1 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm posixshmcontrol | |||||
.Nd Control POSIX shared memory segments | |||||
.Sh SYNOPSIS | |||||
.Nm | |||||
.Ar create | |||||
.Op Fl m Ar mode | |||||
.Op Pa path \&... | |||||
.Nm | |||||
.Ar rm | |||||
.Op Pa path \&... | |||||
.Nm | |||||
.Ar ls | |||||
.Op Fl h | |||||
.Op Fl n | |||||
.Nm | |||||
.Ar dump | |||||
.Op Pa path \&... | |||||
.Nm | |||||
.Ar stat | |||||
.Op Fl h | |||||
.Op Fl n | |||||
.Op Pa path \&... | |||||
.Nm | |||||
.Ar truncate | |||||
.Op Fl s Ar length | |||||
.Op Pa path \&... | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Nm | |||||
command manipulates the named POSIX shared memory segments. | |||||
It allows inspecting existing segments, dumping their metadata or contents, | |||||
and unlinking them. | |||||
.Pp | |||||
Unlinking removes the name from the system and, when the last process | |||||
unmaps the segment and closes file descriptor pointing to the segment, | |||||
frees underlying memory. | |||||
.Pp | |||||
The number of hard links as displayed by the | |||||
.Ic stat | |||||
subcommand, is equal to the number of references to the underlying VM | |||||
object. | |||||
It is almost always equal to the number of mappings +1, except | |||||
for transient references. | |||||
.Pp | |||||
The following subcommands are provided: | |||||
.Bl -tag -width truncate | |||||
.It Ic create | |||||
Create segments with the specified paths, if not exist. | |||||
The | |||||
.Ar mode | |||||
optional numerical argument specifies initial access mode. | |||||
.It Ic rm | |||||
Unlink the paths specified. | |||||
.It Ic ls | |||||
List all linked named shared memory segments visible to the caller. | |||||
For each segment, the user and group owner, size, and path are displayed. | |||||
.It Ic dump | |||||
Output raw bytes values from the segment to standard output. | |||||
.It Ic stat | |||||
Print metadata for the specified path, in the format similar to the | |||||
.Xr stat 1 | |||||
utility. | |||||
.It Ic truncate | |||||
Change the length of the segments. | |||||
Argument to the | |||||
.Fl s | |||||
option specifies new length, the human-friendly 'k', 'm', 'g' suffixes | |||||
can be used, see | |||||
.Xr expand_number 3. | |||||
If the option is not specified, assumed length is zero. | |||||
.El | |||||
.Pp | |||||
For some commands, the following options may be provided: | |||||
.Bl -tag XX | |||||
.It Fl h | |||||
If specified, requests human-readable display of size, see | |||||
.Xr humanize_number 3 . | |||||
.It Fl n | |||||
Prevent translation of owner and group into symbolic names | |||||
using name-switch services, instead the raw numeric values are printed. | |||||
.El | |||||
.Sh EXIT STATUS | |||||
.Ex -std | |||||
.Sh EXAMPLES | |||||
.Bl -bullet | |||||
.It | |||||
To show content of the shared memory segment with the path | |||||
.Pa /1 , | |||||
use the command | |||||
.Dl "posixshmcontrol dump /q | hexdump -C" | |||||
.It | |||||
To create a segment with the path | |||||
.Pa /2 | |||||
and then enlarge it to 1M, use the sequence of commands | |||||
.Dl "posixshmcontrol create /2" | |||||
.Dl "posixshmcontrol truncate -s 1m /2" | |||||
.El | |||||
.Sh SEE ALSO | |||||
.Xr hexdump 1 , | |||||
.Xr stat 1 , | |||||
.Xr ftruncate 2 , | |||||
.Xr read 2 , | |||||
.Xr shm_open 2 , | |||||
.Xr shm_unlink 2 , | |||||
.Xr stat 2 , | |||||
.Xr expand_number 3 , | |||||
.Xr humanize_number 3 , | |||||
.Xr sysctl 3 | |||||
.Sh HISTORY | |||||
The | |||||
.Nm | |||||
command appeared in | |||||
.Fx 13.0 . | |||||
.Sh AUTHORS | |||||
The | |||||
.Nm | |||||
command and this manual page were written by | |||||
.An Konstantin Belousov Aq Mt kib@freebsd.org | |||||
under sponsorship from The FreeBSD Foundation. |