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

[Rodney W. Grimes]

> 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.

I thought the "All rights reserved." had been removed from all
FreeBSD Foundation templates per email from emaste

And thank you for the man page and the utility.

Regards,
Rod

> +.\"
> +.\" 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.
> 
> 

-- 
Rod Grimes                                                 rgrimes at freebsd.org