svn commit: r348359 - head/usr.bin/posixshmcontrol

Wed May 29 13:51:20 UTC 2019

Author: kib
Date: Wed May 29 13:51:18 2019
New Revision: 348359
URL: https://svnweb.freebsd.org/changeset/base/348359

Log:
  Add posixshmcontrol(1) page.
  
  Reviewed by:	emaste
  With input by:	danfe
  Sponsored by:	The FreeBSD Foundation (kib)
  MFC after:	1 week
  Differential revision:	https://reviews.freebsd.org/D20430

Added:
  head/usr.bin/posixshmcontrol/posixshmcontrol.1   (contents, props changed)
Modified:
  head/usr.bin/posixshmcontrol/Makefile

Modified: head/usr.bin/posixshmcontrol/Makefile
==============================================================================

--- head/usr.bin/posixshmcontrol/Makefile	Wed May 29 13:47:10 2019	(r348358)
+++ head/usr.bin/posixshmcontrol/Makefile	Wed May 29 13:51:18 2019	(r348359)
@@ -3,6 +3,5 @@
 PROG=   posixshmcontrol
 LIBADD=	util
 WARNS?=	6
-MAN=
 
 .include <bsd.prog.mk>

Added: head/usr.bin/posixshmcontrol/posixshmcontrol.1
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/usr.bin/posixshmcontrol/posixshmcontrol.1	Wed May 29 13:51:18 2019	(r348359)
@@ -0,0 +1,153 @@
+.\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This documentation was written by
+.\" Konstantin Belousov <kib at 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 at freebsd.org
+under sponsorship from The FreeBSD Foundation.
