.TH SHMCAT "1" "August 2016" "shmcat(1)"
.SH NAME
shmcat \- dump shared memory segments, files, standard input and/or text
.SH SYNOPSIS
.B shmcat [
.I OPTION
.B ]... [
.I OPERAND
.B ]...
.SH DESCRIPTION
Dump shared memory segments, files, standard input and/or text to standard
output. If no OPERAND is given, read standard input only. If more
than one OPERAND is given, dump them in order. If some of the OPERANDs
cannot be read, shmcat prints an error message to standard error and tries
to continue with the other OPERANDs, unless the \fB-S\fR or \fB--stop\fR
option is given.
.PP
Most modern systems support two APIs for shared memory:
.PP
The older one is commonly known as the System V API. It uses numeric keys
and IDs as identifiers and consists of system calls like \fBshmget(2)\fR,
\fBshmat(2)\fR and \fBshmdt(2)\fR.
.PP
The newer API is called the POSIX shared memory API. It uses names in string
form as identifiers. It treats shared memory similar to files, which are
opened with \fBshm_open(3)\fR and then mapped into the program address space
via \fBmmap(2)\fR. Please note that POSIX shared memory is not supported by all
versions of shmcat.
.PP
If shmcat has been compiled without \fBgetopt_long(3)\fR support, only the
short, one character OPTIONs and OPERANDs can be used. Otherwise the long ones
are also available. When a long OPTION or OPERAND needs an argument, the short
versions do so, as well.
.SH OPTIONS
.TP
\fB-h\fR, \fB-?\fR, \fB--help\fR
Display usage information and quit without dumping anything.
.TP
\fB-S\fR, \fB--stop\fR
By default, if an OPERAND cannot be read, shmcat tries to continue with the
remaining OPERANDs. This option turns of that behavior, so that the program
stops immediately after the first OPERAND that cannot be read.
.TP
\fB-V\fR, \fB--version\fR
Show version information and quit without further action.
.SH OPERANDS
.TP
\fB-f\fR, \fB--file=\fIFILENAME\fR
Dump the contents of the given file.
.TP
\fB-i\fR, \fB--stdin\fR
Dump standard input.
.TP
\fB-M\fR, \fB--shmkey=\fIKEY\fR
Dump the System V shared memory segment with the given key. The key can be
given as a decimal (no prefix), octal (prefix \fB0\fR), or hexadecimal
(prefix \fB0x\fR) number. It can, for example, be obtained using the
\fBipcs(1)\fR or the \fBftok(1)\fR tool.
.TP
\fB-m\fR, \fB--shmid=\fIID\fR
Dump the System V shared memory segment with the given id. The id can be
given as a decimal (no prefix), octal (prefix \fB0\fR), or hexadecimal
(prefix \fB0x\fR) number. It can, for example, be obtained using the
\fBipcs(1)\fR tool.
.TP
\fB-n\fR, \fB--newline\fR
Add a line feed.
.TP
\fB-p\fR, \fB--posix-shm=\fINAME\fR
Dump the POSIX shared memory segment with the given name (not supported in
all installations).
.TP
\fB-t\fR, \fB--text=\fITEXT\fR
Print the given text.
.SH EXIT CODES
.TP
0
No errors, every OPERAND requested was dumped.
.TP
1
There was an error while opening or reading at least one OPERAND. If shmcat
has been invoked with the \fB-S\fR or \fB--stop\fR option, the program stopped
after this error, otherwise it tried to continue with the remaining OPERANDs
(if given).
.TP
2
There was a fatal error, usually this means that shmcat could not write to standard output.
.TP
10
Wrong usage of the program.
.SH NOTES
Usually, when you dump shared memory segments, you should redirect the
output of shmcat to a file or a program like \fBod(1)\fR, because shared
memory data usually has a binary form and thus it may contain
non-printable characters. You also probably want to suspend the processes
writing to the shared memory object in order to get a consistent dump.
.SH AUTHOR
Stefan Gast
.SH "SEE ALSO"
.BR ftok(1),
.BR ipcs(1),
.BR shmat(2),
.BR shmget(2),
.BR shm_open(3)