path: root/man/procenv.1

.TH PROCENV "1" "2016-03-10" "User Commands"
.\"
.SH NAME
procenv \- display process environment details
.\" Macros
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\"
.SH SYNOPSIS
.B procenv
[\fIOPTION\fR]
.\"
.SH DESCRIPTION
Display details of the process environment in a parseable format.
.\"
.SH OPTIONS
.\"
Options shown with a bracketed asterisk \(aq(*)\(aq are non-display
options and must preceed any other (display) options.

.TP
\fB\-a\fR, \fB\-\-meta\fR
Display meta details.
.\"
.TP
\fB\-A\fR, \fB\-\-arguments\fR
Display program arguments.
.\"
.TP
\fB\-b\fR, \fB\-\-libs\fR
Display details of linked libraries.
See
.BR dl_iterate_phdr (3) "" .
.\"
.TP
\fB\-B\fR, \fB\-\-libc\fR
Display standard library details.
See
.BR feature_test_macros (7) "" " (Linux)."
.\"
.TP
\fB\-c\fR, \fB\-\-cgroups\fR
Display cgroup details (Linux only).
See
.BR proc (5) "" .
.\"
.TP
\fB\-C\fR, \fB\-\-cpu\fR
Display CPU and scheduler details.
See
.BR kvm_getprocs (3) "" " (BSD), "
.BR pthread_getaffinity_np (3) ", "
.BR sched_getcpu (3) "" " (Linux)" "" "."
.\"
.TP
\fB\-\-crumb\-separator=\fR\fIstr\fR (*)
Specify string
.I str
as alternate delimiter for crumb format output (default=\(aq:\(aq).
.\"
.TP
\fB\-d\fR, \fB\-\-compiler\fR
Display compiler details.
See
.BR cpp (1) "" ", " cc (1) "" " and " feature_test_macros (7) "" " (Linux)."
.\"
.TP
\fB\-e\fR, \fB\-\-environment\fR
Display environment variables.
See
.BR environ (7) "" .
.\"
.TP
\fB\-E\fR, \fB\-\-semaphores\fR
Display semaphore details (not queryable on BSD).
See
.BR semctl (2) "" .
.\"
.TP
\fB\-\-exec\fR (*)
Treat non-option arguments as program to execute after running
\fBprocenv\fR.
See
.BR exec (3) "" .
.\"
.TP
\fB\-f\fR, \fB\-\-fds\fR
Display file descriptor details. Under FreeBSD, file descriptor
capabilities will also be displayed assuming the kernel has Capsicum
support.
See
.BR cap_getmode (2) "" " (BSD)" "" ", "
.BR cap_rights_get (2) "" " (BSD)" "" ", "
.BR cap_rights_is_set (3) "" " (BSD)" "" ", "
.BR fcntl (2) "" ", "
.BR isatty (5) "" "."
.\"
.TP
\fB\-F\fR, \fB\-\-namespaces\fR
Display namespace details (Linux only).
See
.BR proc (5) "" .
.\"
.TP
\fB\-\-file=\fR\fIFILE\fR (*)
Send output to file \fIFILE\fR (implies \fB\-\-output=file\fR).
.\"
.TP
\fB\-\-file\-append\fR (*)
If \fB\-\-file\fR is specifed, append to it rather than
overwriting it.
.PP
.\"
.TP
\fB\-\-format=\fR\fIFORMAT\fR (*)
Specify output format.
.I FORMAT
may be one of:
.RS
.IP \(bu 4
\fIcrumb\fR ("breadcrumbs").
.IP \(bu 4
\fIjson\fR (JavaScript Object Notation).
.IP \(bu 4
\fItext\fR (plain ASCII text) [default].
.IP \(bu 4
\fIxml\fR (Extensible Markup Language).
.RE
.PP
.\"
.TP
\fB\-g\fR, \fB\-\-sizeof\fR
Display sizes of data types.
.\"
.TP
\fB\-h\fR, \fB\-\-help\fR
This help text.
.\"
.TP
\fB\-i\fR, \fB\-\-misc\fR
Display miscellaneous details.
See
.BR umask (P) "" ", "
.BR getcwd (3) "" ", "
.BR personality (2) "" " (Linux), "
.BR proc (5) "" ", "
.BR prctl (2) "" ", "
.BR aa_getcon (2) "" " (Linux), "
.BR getpidcon (3) "" " (Linux), "
.BR sysconf (3) "" ", "
.BR kvm_getprocs (3) "" " (BSD), "
.BR getpriority (2) "" .
.\"
.TP
\fB\-\-indent\fR (*)
Number of indent characters to use for each indent
(default=2).
.\"
.TP
\fB\-\-indent\-char=\fR\fIc\fR (*)
Use character
.I c
for indenting
(default=\(aq \(aq (space)).
.\"
.TP
\fB\-j\fR, \fB\-\-uname\fR
Display uname details.
See
.BR uname (2) "" .
.\"
.TP
\fB\-k\fR, \fB\-\-clocks\fR
Display clock details.
See
.BR clock_getres (2) "" .
.\"
.TP
\fB\-l\fR, \fB\-\-limits\fR
Display limits.
See
.BR getrlimit (2) "" .
.\"
.TP
\fB\-L\fR, \fB\-\-locale\fR
Display locale details.
See
.BR setlocale (3) "" " and " locale (7) "" .
.\"
.TP
\fB\-m\fR, \fB\-\-mounts\fR
Display mount details.
See
.BR getmntent (3) "" " and " statfs (2) "" " (Linux), and " getmntinfo (3) "" " (BSD)."
.PP
.\"
.TP
\fB\-M\fR, \fB\-\-message\-queues\fR
Display message queue details (not queryable on BSD).
See
.BR msgctl (2) "" .
.\"
.TP
\fB\-n\fR, \fB\-\-confstr\fR
Display confstr details.
See
.BR confstr (5) "" .
.PP
.\"
.TP
\fB\-N\fR, \fB\-\-network\fR
Display network details.
See
.BR getifaddrs (3) "" ", " getnameinfo (3) "" ", " ip (7) "" ", " netdevice (7) "" ", and " ioctl (2) " (Linux)" .
.PP
.\"
.TP
\fB\-o\fR, \fB\-\-oom\fR
Display out-of-memory manager details (Linux only).
See
.BR proc (5) "" .
.PP
.\"
.TP
\fB\-\-output=\fR\fITYPE\fR (*)
Send output to alternative location. \fITYPE\fR can be one of:
.RS
.IP \(bu 4
\fIfile\fR (send output to a file).
.IP \(bu 4
\fIstderr\fR (write to standard error).
.IP \(bu 4
\fIstdout\fR (write to standard output (default)).
.IP \(bu 4
\fIsyslog\fR (write to the system log file).
.IP \(bu 4
\fIterminal\fR (write to terminal).
.RE
.PP
.\"
.TP
\fB\-p\fR, \fB\-\-process\fR
Display process details.
See
.BR getpid (2) "" ", "
.BR getppid (2) "" ", "
.BR getresuid (2) "" ", "
.BR getresgid (2) "" ", "
.BR getuid (2) "" ", "
.BR geteuid (2) "" ", "
.BR getgid (2) "" ", "
.BR getegid (2) "" ", "
.BR getsid (2) "" ", "
.BR getlogin (3) "" ", "
.BR getpgrp (2) "" ", "
.BR ctermid (3) "" ", "
.BR tcgetpgrp (3) "" ", "
.BR tcgetsid (3) "" ", "
.BR getpwuid (3) "" " and "
.BR getgroups (2) "" .
.PP
.\"
.TP
\fB\-P\fR, \fB\-\-platform\fR
Display platform details.
.\"
.TP
\fB\-q\fR, \fB\-\-time\fR
Display time details.
See
.BR clock_gettime (2) "" ", "
.BR localtime (3) "" " and "
.BR asctime (3) "" .
.PP
.\"
.TP
\fB\-r\fR, \fB\-\-ranges\fR
Display range of data types.
See
.BR limits.h (P) "" .
.PP
.\"
.TP
\fB\-s\fR, \fB\-\-signals\fR
Display signal details.
See
.BR sigaction (2) "" .
.PP
.\"
.TP
\fB\-S\fR, \fB\-\-shared\-memory\fR
Display shared memory details (not queryable on BSD).
See
.BR shmctl (2) "" .
.PP
.\"
.TP
\fB\-\-separator=\fR\fIstr\fR (*)
Specify string
.I str
as alternate delimiter for text format output (default=\(aq: \(aq).
.\"
.TP
\fB\-t\fR, \fB\-\-tty\fR
Display terminal details. On Linux, will also show if any attributes are
locked when running as
.IR root "."
See
.BR tcgetattr (3) "" " and " "" " " tty_ioctl (4) "" " (Linux)."
.PP
.\"
.TP
\fB\-T\fR, \fB\-\-threads\fR
Display thread details.
See
.BR pthread_attr_getstacksize (3) "" ", "
.BR pthread_attr_getstacksize (3) "" " and "
.BR pthread_attr_getguardsize (3) "" .
.PP
.\"
.TP
\fB\-u\fR, \fB\-\-stat\fR
Display stat details.
See
.BR stat (2) "" .
.PP
.\"
.TP
\fB\-U\fR, \fB\-\-rusage\fR
Display rusage details.
See
.BR getrusage (2) "" .
.PP
.\"
.TP
\fB\-v\fR, \fB\-\-version\fR
Display version details.
.PP
.\"
.TP
\fB\-w\fR, \fB\-\-capabilities\fR
Display Linux capability details. For FreeBSD file descriptor
capabilities, see \fB\-\-file\-descriptors\fR.
See
.BR prctl (2) "" " (Linux)" "" ","
.BR libcap (3) "" " (Linux)" "" "."
.PP
.\"
.TP
\fB\-x\fR, \fB\-\-pathconf\fR
Display pathconf details.
See
.BR pathconf (3) "" .
.PP
.\"
.TP
\fB\-y\fR, \fB\-\-sysconf\fR
Display sysconf details.
See
.BR sysconf (3) "" " and " posixoptions (7) "" " (Linux)."
.PP
.\"
.TP
\fB\-Y\fR, \fB\-\-memory\fR
Display memory details.
See
.BR getpagesize (2) "" ", "
.BR numa (3) "" " (Linux) and " numa (7) "" " (Linux)."
.PP
.\"
.TP
\fB\-z\fR, \fB\-\-timezone\fR
Display timezone details.
See
.BR tzset (3) "" .
.PP
.\"
.SH ENVIRONMENT VARIABLES
.\"
The following environment variables may be used as aliases to their
command-line counterparts:
.\"
.TP
\fBPROCENV_CRUMB_SEPARATOR\fR
Alternative to \fB\-\-crumb\-separator\fR.
.PP
.\"
.TP
\fBPROCENV_EXEC\fR
Alternative to \fB\-\-exec\fR.
.PP
.\"
.TP
\fBPROCENV_FILE\fR
Alternative to \fB\-\-file\fR.
.\"
.TP
\fBPROCENV_FILE_APPEND\fR
Alternative to \fB\-\-file\-append\fR.
.PP
.\"
.TP
\fBPROCENV_FORMAT\fR
Alternative to \fB\-\-format\fR.
.PP
.\"
.TP
\fBPROCENV_INDENT\fR
Alternative to \fB\-\-indent\fR.
.PP
.\"
.TP
\fBPROCENV_INDENT_CHAR\fR
Alternative to \fB\-\-indent\-char\fR.
.PP
.\"
.TP
\fBPROCENV_SEPARATOR\fR
Alternative to \fB\-\-separator\fR.
.PP
.\"
.TP
\fBPROCENV_OUTPUT\fR
Alternative to \fB\-\-output\fR.
.PP
.\"
.SH NOTES
.IP \(bu 4
Options are considered in order, so \fB\-\-output\fR should
precede any other option.
.IP \(bu 4
If no display option is specified, all details are displayed.
.IP \(bu
Only one display option may be specified.
.IP \(bu
Command-line options take priority over environment variables.
.IP \(bu
All values for \fB\-\-indent\-char\fR are literal except \(aq\\t\(aq which can be
used to specify a tab character. The same is true for \fB\-\-separator\-char\fR and
\fB\-\-crumb\-separator\fR but only if it is the first character
specified.
.IP \(bu
Specifying a visible indent\-char is only (vaguely) meaningful for text output.
.IP \(bu
If \fB\-\-exec\fR is specified, atleast one non-option argument must also be
specified.
.IP \(bu
Any long option name may be shortened as long as it remains unique.
.IP \(bu
The
.I crumb
output format is designed for easy parsing: it displays the data in a
flattened format with each value on a separate line preceded by all
appropriate headings which are separated by the current separator.
.IP \(bu
The \fB\-\-message\-queues\fR, \fB\-\-semaphores\fR and 
\fB\-\-shared\-memory\fR options are not available on BSD since although
the values are queryable, there is no documented method to do so.
.sp 1
.\"
.SH EXAMPLES
.\"
.Vb
\& # Show limits
\& procenv \-l
\&
\& # Send compiler information to syslog (note the order of the options).
\& procenv \-\-output=syslog \-\-compiler
\&
\& # Write compiler details direct to the terminal
\& procenv \-\-output=terminal \-\-compiler
\&
\& # Run a command ('mycmd \-\-arg1 \-\-foo=bar') without creating a new
\& # process, but have procenv run first and log its output to a
\& # regular file.
\& exec procenv \-\-file=/tmp/procenv.log \-\-exec \-\- mycmd \-\-arg1 \-\-foo=bar
\&
\& # The following kernel command-line snippet will cause procenv to
\& # write output to first serial tty device and then execute init(8)
\& # in debug mode to allow early boot environment to be examined.
\& init=/usr/bin/procenv PROCENV_FILE=/dev/ttyS0 PROCENV_EXEC="/sbin/init \-\-debug"
\&
\& # Display all data in JSON format using an indent of 4 spaces
\& procenv \-\-format=json \-\-indent=4
\&
\& # Display all data in XML format using tabs for indents
\& procenv \-\-format=xml \-\-indent\-char="\\t"
\&
\& # Display signal details in XML format
\& procenv \-\-format=xml \-\-signals
\&
\& # Display resource limits in easily-parseable format
\& procenv \-\-format=crumb \-\-limits
\&
\& # Produce output suitable for importing into a spreadsheet
\& procenv \-\-format=crumb \-\-crumb\-separator=\(aq,\(aq \-\-separator=\(aq,\(aq \-\-limits
\&
\& # Produce stylised output
\& procenv \-\-format=crumb \-\-crumb\-separator=\(aq \[u2192] \(aq \-\-separator=\(aq=\(aq
\&
.Ve
.Ve
.\"
.SH LIMITATIONS
.IP \(bu 4
Spaces within the value of \fBPROCENV_EXEC\fR are treated as delimiters
meaning that any spaces within a string argument for example will result in
incorrect behaviour.
.IP \(bu 4
The separator character must be chosen carefully since no check is
performed on the data to see if
.I it itself
contains instances of the separator character.
.\"
.SH AUTHORS
Written by
James Hunt
.RB < jamesodhunt@ubuntu.com >
and
Kees Cook
.RB < kees@ubuntu.com > "" "."
.\"
.SH COPYRIGHT
Copyright \(co 2012-2016 James Hunt
.RB < jamesodhunt@ubuntu.com >
and
Kees Cook
.RB < kees@ubuntu.com > "" "."
.br
This is free software; see the source for copying conditions.  There is
NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
.\"
.SH LICENSE
GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\"
.SH SEE ALSO
.BR capabilities (7) "" " (Linux), "
.BR capsicum (4) "" " (BSD)" "" ", "
.BR cc (1) "" ,
.BR credentials (7) "" ,
.BR date (1) "" ,
.BR env (1) "" ,
.BR exec (P) "" ,
.BR getconf (1) "" ,
.BR groups (1) "" ,
.BR ifconfig (8) "" ,
.BR ip (9) "" ,
.BR ipcs (1) "" ,
.BR kill (1) "" ,
.BR ldd (1) "" ,
.BR locale (1) "" ,
.BR ls (1) "" ,
.BR mount (1) "" ,
.BR proc (5) "" ,
.BR ps (1) "" ,
.BR rights (4) "" (BSD),
.BR sh (1) "" ,
.BR stat (1) "" ,
.BR stty (1) "" ,
.BR umask (P) "" ,
.BR uname (1)