Merge branch 'hardlink' of https://github.com/rudimeier/util-linux into hardlink

[thirdparty/util-linux.git] / misc-utils / mcookie.1

diff --git a/misc-utils/mcookie.1 b/misc-utils/mcookie.1
index 90cff1babccd48ccfe070b95182bdcccedd6962d..1ac50ef139e0a2eb864d46a9b017964c8a1e9841 100644 (file)
--- a/misc-utils/mcookie.1
+++ b/misc-utils/mcookie.1
@@ -1,51 +1,69 @@
-.\" mcookie.1 -- 
+.\" mcookie.1 --
 .\" Public Domain 1995 Rickard E. Faith (faith@cs.unc.edu)
-.TH MCOOKIE 1 "25 September 1995" "" "Linux Programmer's Manual"
+.TH MCOOKIE 1 "December 2014" "util-linux" "User Commands"
 .SH NAME
 mcookie \- generate magic cookies for xauth
 .SH SYNOPSIS
-.BI "mcookie [\-v] [\-f " filename " ]"
+.B mcookie
+[options]
 .SH DESCRIPTION
 .B mcookie
 generates a 128-bit random hexadecimal number for use with the X authority
 system.  Typical usage:
+.sp
 .RS
-xauth add :0 . `mcookie`
+.B xauth add :0 . `mcookie`
 .RE
 .PP
-The "random" number generated is actually the output of the MD5 message
-digest fed with various piece of random information: the current time, the
-process id, the parent process id, the contents of an input file (if
-.B \-f
-is specified), and several bytes of information from the first of the
-following devices which is present:
-.IR /dev/random ,
+The "random" number generated is actually the MD5 message
+digest of random information coming from one of the sources
+.IR getrandom ()
+system call,
 .IR /dev/urandom ,
-files in
-.IR /proc ,
-.IR /dev/audio .
+.IR /dev/random ,
+or the
+.IR "libc pseudo-random functions" ,
+in this preference order. See also the option \fB\-\-file\fR.
+.SH OPTIONS
+.TP
+.BR \-f , " \-\-file " \fIfile
+Use this \fIfile\fR as an additional source of randomness (for example /dev/urandom).
+When \fIfile\fR is '-', characters are read from standard input.
+.TP
+.BR \-m , " \-\-max\-size " \fInumber
+Read from \fIfile\fR only this \fInumber\fR of bytes.
+This option is meant to be used when reading additional
+randomness from a file or device.
+.IP
+The
+.I number
+argument may be followed by the multiplicative suffixes KiB=1024,
+MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is
+optional, e.g., "K" has the same meaning as "KiB") or the suffixes
+KB=1000, MB=1000*1000, and so on for GB, TB, PB, EB, ZB and YB.
+.TP
+.BR \-v , " \-\-verbose"
+Inform where randomness originated, with amount of entropy read from each
+source.
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
 .SH BUGS
-The entropy in the generated 128-bit is probably quite small (and,
-therefore, vulnerable to attack) unless a non-pseudorandom number generator
-is used (e.g.,
-.I /dev/random
-under Linux).
-.PP
-It is assumed that none of the devices opened will block.
+It is assumed that none of the randomness sources will block.
 .SH FILES
-.I /dev/random
-.br
 .I /dev/urandom
 .br
-.I /dev/audio
-.br
-.I /proc/stat
-.br
-.I /proc/loadavg
+.I /dev/random
 .SH "SEE ALSO"
+.BR md5sum (1),
 .BR X (1),
 .BR xauth (1),
-.BR md5sum (1)
+.BR rand (3)
 .SH AVAILABILITY
-The mcookie command is part of the util-linux-ng package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.
+The mcookie command is part of the util-linux package and is available from
+.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .