Add man page and README file

Makefile.am

@@ -1,5 +1,5 @@
-SUBDIRS = lib src
+SUBDIRS = lib src man
 
 ACLOCAL_AMFLAGS = -I m4 --install
 
-dist_doc_DATA = AUTHORS COPYING
+dist_doc_DATA = AUTHORS COPYING README

README

@@ -0,0 +1,41 @@
+scdrand - Extract random numbers from a smartcard
+=================================================
+
+Description
+-----------
+scdrand obtains up to 256 bytes of random data from a ISO7816-compliant
+smartcard and adds them to the kernel entropy pool.
+
+
+Principles
+----------
+scdrand uses scdaemon, the smartcard daemon of the GnuPG project, to
+send a GET CHALLENGE command to a smartcard. As per ISO 7816-4, the
+smartcard replies with random bytes, which scdrand then sends to the
+Linux kernel entropy pool through the RNDADDENTROPY ioctl call on
+/dev/random.
+
+Since that call requires root privileges, scdrand is installed with the
+setuid bit set. To mitigate risks associated with running as root, the
+program forks itself at startup and only the child retains the root
+privileges needed to write to /dev/random. The parent process, in charge
+of communicating with the smartcard, then runs with the privileges on
+the calling user.
+
+
+Copying
+-------
+scdrand is distributed under the terms of the GNU General Public
+License, version 3 or higher. The full license is included in the
+COPYING file of the source distribution.
+
+
+Homepage and contact
+--------------------
+The project is located at <http://www.incenp.org/dvlpt/scdrand.html>.
+The latest source code is available in a Git repository at
+<git://git.incenp.org/scdrand.git> and may also be browsed at
+<http://www.incenp.org/gitweb/?p=scdrand.git;a=summary>.
+
+The author may be contact at the following address:
+Damien Goutte-Gattat <dgouttegattat@incenp.org>

configure.ac

@@ -29,7 +29,8 @@ AM_PATH_GPG_ERROR([1.11],
                   [AC_MSG_ERROR([libgpg-error not found])])
 
 dnl Output files
-AC_CONFIG_FILES([Makefile lib/Makefile src/Makefile])
+AC_CONFIG_FILES([Makefile lib/Makefile src/Makefile
+                 man/Makefile man/scdrand.1])
 AC_OUTPUT
 
 dnl Summary

man/Makefile.am

@@ -0,0 +1 @@
+man_MANS = scdrand.1

man/scdrand.1.in

@@ -0,0 +1,85 @@
+.TH SCDRAND 11/08/2014 "scdrand @PACKAGE_VERSION@"
+
+.SH NAME
+scdrand \- Extract random numbers from a smartcard
+
+.SH SYNOPSIS
+.SY scdrand
+.RB [ \-h | --help ]
+.RB [ \-v | --version ]
+.RB [ \-l | --loop ]
+.RB [ \-L | --max-loop
+.IR N ]
+.RB [ \-i | --interval
+.IR N ]
+.RB [ \-t | --threshold
+.IR N ]
+.RB [ nbytes ]
+.YS
+
+.SH DESCRIPTION
+.PP
+.B scdrand
+fetches random bytes from a ISO7816-compliant smartcard
+and feeds them to the Linux kernel entropy pool.
+.PP
+The program depends on
+.I scdaemon
+(part of GnuPG) to interact with a card reader and the
+card itself.
+
+.SH OPTIONS
+.TP
+.BR -h ", " --help
+Display the help message.
+.TP
+.BR -v ", " --version
+Display the version message.
+.TP
+.BR -l ", " --loop
+Loop indefinitely.
+.TP
+.BR -L ", " --max-loop " " \fiN\fR
+Loop for
+.I N
+iterations.
+.TP
+.BR -i ", " --interval " " \fiN\fR
+Sleep for
+.I N
+seconds between iterations.
+.TP
+.BR -t ", " --threshold " " \fiN\fR
+Feed the kernel entropy pool only if it contains less than
+.N N
+bits of entropy.
+
+.SH EXAMPLES
+.PP
+Check the kernel entropy pool every 5 seconds, and feed it with
+64 bytes of random data if there is less than 512 bits of
+entropy available:
+.PP
+.nf
+$ scdrand -l -i 5 -t 512 64
+
+.SH REPORTING BUGS
+.PP
+Report bugs to
+.MT @PACKAGE_BUGREPORT@
+Damien Goutte-Gattat
+.ME .
+
+.SH SEE ALSO
+.BR scdaemon (1),
+.BR random (4)
+
+.SH COPYRIGHT
+.ad l
+.PP
+Copyright \(co 2014 Damien Goutte-Gattat
+.PP
+This program is released under the GNU General Public License.
+See the COPYING file in the source distribution or
+.UR http://www.gnu.org/licenses/gpl.html
+.UE .