9971 Make getrandom(2) a public interface

Reviewed by: Dan McDonald <danmcd@joyent.com>
Reviewed by: Mike Gerdts <mike.gerdts@joyent.com>
Reviewed by: Peter Tribble <peter.tribble@gmail.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Andy Fiddaman <omnios@citrus-it.net>
Reviewed by: Igor Kozhukhov <igor@dilos.org>
Approved by: Joshua M. Clulow <josh@sysmgr.org>

2 files changed, 357 insertions, 222 deletions

diff --git a/usr/src/man/man2/Makefile b/usr/src/man/man2/Makefile
index 05f38f9f24..556de2d03b 100644
--- a/usr/src/man/man2/Makefile
+++ b/usr/src/man/man2/Makefile
@@ -13,248 +13,249 @@
 # Copyright 2011, Richard Lowe
 # Copyright 2013, OmniTI Computer Consulting, Inc
 # Copyright 2013 Nexenta Systems, Inc.  All rights reserved.
-# Copyright (c) 2015, Joyent, Inc.  All rights reserved.
+# Copyright (c) 2018, Joyent, Inc.  All rights reserved.
 # Copyright 2017 Peter Tribble
 #
 
 include		$(SRC)/Makefile.master
 
-MANSECT= 	2
+MANSECT=	2
 
 MANFILES=	Intro.2			\
-	 	__sparc_utrap_install.2 \
-	 	_lwp_cond_signal.2	\
-	 	_lwp_cond_wait.2	\
-	 	_lwp_info.2		\
-	 	_lwp_kill.2		\
-	 	_lwp_mutex_lock.2	\
-	 	_lwp_self.2		\
-	 	_lwp_sema_wait.2	\
-	 	_lwp_suspend.2		\
-	 	access.2		\
-	 	acct.2			\
-	 	acl.2			\
-	 	adjtime.2		\
-	 	alarm.2			\
-	 	audit.2			\
-	 	auditon.2		\
-	 	brk.2			\
-	 	chdir.2			\
-	 	chmod.2			\
-	 	chown.2			\
-	 	chroot.2		\
-	 	close.2			\
-	 	creat.2			\
-	 	dup.2			\
-	 	exec.2			\
-	 	exit.2			\
-	 	fcntl.2			\
-	 	fork.2			\
-	 	fpathconf.2		\
-	 	getacct.2		\
-	 	getaudit.2		\
-	 	getauid.2		\
-	 	getcontext.2		\
-	 	getdents.2		\
-	 	getgroups.2		\
-	 	getisax.2		\
-	 	getitimer.2		\
-	 	getmsg.2		\
-	 	getpflags.2		\
-	 	getpid.2		\
-	 	getppriv.2		\
-	 	getrlimit.2		\
-	 	getsid.2		\
-	 	getuid.2		\
-	 	getustack.2		\
-	 	ioctl.2			\
-	 	issetugid.2		\
-	 	kill.2			\
-	 	link.2			\
-	 	llseek.2		\
-	 	lseek.2			\
-	 	memcntl.2		\
-	 	meminfo.2		\
-	 	mincore.2		\
-	 	mkdir.2			\
-	 	mknod.2			\
-	 	mmap.2			\
-	 	mmapobj.2		\
-	 	mount.2			\
-	 	mprotect.2		\
-	 	msgctl.2		\
-	 	msgget.2		\
-	 	msgids.2		\
-	 	msgrcv.2		\
-	 	msgsnap.2		\
-	 	msgsnd.2		\
-	 	munmap.2		\
-	 	nice.2			\
-	 	ntp_adjtime.2		\
-	 	ntp_gettime.2		\
-	 	open.2			\
-	 	p_online.2		\
-	 	pause.2			\
-	 	pcsample.2		\
-	 	pipe.2			\
-	 	poll.2			\
-	 	priocntl.2		\
-	 	priocntlset.2		\
-	 	processor_bind.2	\
-	 	processor_info.2	\
-	 	profil.2		\
-	 	pset_bind.2		\
-	 	pset_create.2		\
-	 	pset_info.2		\
-	 	pset_list.2		\
-	 	pset_setattr.2		\
-	 	putmsg.2		\
-	 	read.2			\
-	 	readlink.2		\
-	 	rename.2		\
-	 	resolvepath.2		\
-	 	rmdir.2			\
-	 	semctl.2		\
-	 	semget.2		\
-	 	semids.2		\
-	 	semop.2			\
-	 	setpgid.2		\
-	 	setpgrp.2		\
-	 	setrctl.2		\
-	 	setregid.2		\
-	 	setreuid.2		\
-	 	setsid.2		\
-	 	settaskid.2		\
-	 	setuid.2		\
-	 	shmctl.2		\
-	 	shmget.2		\
-	 	shmids.2		\
-	 	shmop.2			\
-	 	sigaction.2		\
-	 	sigaltstack.2		\
-	 	sigpending.2		\
-	 	sigprocmask.2		\
-	 	sigsend.2		\
-	 	sigsuspend.2		\
-	 	sigwait.2		\
-	 	stat.2			\
-	 	statvfs.2		\
-	 	stime.2			\
-	 	swapctl.2		\
-	 	symlink.2		\
-	 	sync.2			\
-	 	sysfs.2			\
-	 	sysinfo.2		\
-	 	time.2			\
-	 	times.2			\
-	 	uadmin.2		\
-	 	ulimit.2		\
-	 	umask.2			\
-	 	umount.2		\
-	 	uname.2			\
-	 	unlink.2		\
-	 	ustat.2			\
-	 	utime.2			\
-	 	utimes.2		\
-	 	uucopy.2		\
-	 	vfork.2			\
-	 	vhangup.2		\
-	 	waitid.2		\
-	 	write.2			\
-	 	yield.2			\
+		__sparc_utrap_install.2 \
+		_lwp_cond_signal.2	\
+		_lwp_cond_wait.2	\
+		_lwp_info.2		\
+		_lwp_kill.2		\
+		_lwp_mutex_lock.2	\
+		_lwp_self.2		\
+		_lwp_sema_wait.2	\
+		_lwp_suspend.2		\
+		access.2		\
+		acct.2			\
+		acl.2			\
+		adjtime.2		\
+		alarm.2			\
+		audit.2			\
+		auditon.2		\
+		brk.2			\
+		chdir.2			\
+		chmod.2			\
+		chown.2			\
+		chroot.2		\
+		close.2			\
+		creat.2			\
+		dup.2			\
+		exec.2			\
+		exit.2			\
+		fcntl.2			\
+		fork.2			\
+		fpathconf.2		\
+		getacct.2		\
+		getaudit.2		\
+		getauid.2		\
+		getcontext.2		\
+		getdents.2		\
+		getgroups.2		\
+		getisax.2		\
+		getitimer.2		\
+		getmsg.2		\
+		getpflags.2		\
+		getpid.2		\
+		getppriv.2		\
+		getrandom.2		\
+		getrlimit.2		\
+		getsid.2		\
+		getuid.2		\
+		getustack.2		\
+		ioctl.2			\
+		issetugid.2		\
+		kill.2			\
+		link.2			\
+		llseek.2		\
+		lseek.2			\
+		memcntl.2		\
+		meminfo.2		\
+		mincore.2		\
+		mkdir.2			\
+		mknod.2			\
+		mmap.2			\
+		mmapobj.2		\
+		mount.2			\
+		mprotect.2		\
+		msgctl.2		\
+		msgget.2		\
+		msgids.2		\
+		msgrcv.2		\
+		msgsnap.2		\
+		msgsnd.2		\
+		munmap.2		\
+		nice.2			\
+		ntp_adjtime.2		\
+		ntp_gettime.2		\
+		open.2			\
+		p_online.2		\
+		pause.2			\
+		pcsample.2		\
+		pipe.2			\
+		poll.2			\
+		priocntl.2		\
+		priocntlset.2		\
+		processor_bind.2	\
+		processor_info.2	\
+		profil.2		\
+		pset_bind.2		\
+		pset_create.2		\
+		pset_info.2		\
+		pset_list.2		\
+		pset_setattr.2		\
+		putmsg.2		\
+		read.2			\
+		readlink.2		\
+		rename.2		\
+		resolvepath.2		\
+		rmdir.2			\
+		semctl.2		\
+		semget.2		\
+		semids.2		\
+		semop.2			\
+		setpgid.2		\
+		setpgrp.2		\
+		setrctl.2		\
+		setregid.2		\
+		setreuid.2		\
+		setsid.2		\
+		settaskid.2		\
+		setuid.2		\
+		shmctl.2		\
+		shmget.2		\
+		shmids.2		\
+		shmop.2			\
+		sigaction.2		\
+		sigaltstack.2		\
+		sigpending.2		\
+		sigprocmask.2		\
+		sigsend.2		\
+		sigsuspend.2		\
+		sigwait.2		\
+		stat.2			\
+		statvfs.2		\
+		stime.2			\
+		swapctl.2		\
+		symlink.2		\
+		sync.2			\
+		sysfs.2			\
+		sysinfo.2		\
+		time.2			\
+		times.2			\
+		uadmin.2		\
+		ulimit.2		\
+		umask.2			\
+		umount.2		\
+		uname.2			\
+		unlink.2		\
+		ustat.2			\
+		utime.2			\
+		utimes.2		\
+		uucopy.2		\
+		vfork.2			\
+		vhangup.2		\
+		waitid.2		\
+		write.2			\
+		yield.2			\
 
 MANLINKS=	_Exit.2				\
-	 	_exit.2				\
-	 	_lwp_cond_broadcast.2		\
-	 	_lwp_cond_reltimedwait.2	\
-	 	_lwp_cond_timedwait.2		\
-	 	_lwp_continue.2			\
-	 	_lwp_mutex_trylock.2		\
-	 	_lwp_mutex_unlock.2		\
-	 	_lwp_sema_init.2		\
-	 	_lwp_sema_post.2		\
-	 	_lwp_sema_trywait.2		\
-	 	execl.2				\
-	 	execle.2			\
-	 	execlp.2			\
-	 	execv.2				\
-	 	execve.2			\
-	 	execvp.2			\
-	 	faccessat.2			\
-	 	facl.2				\
-	 	fchdir.2			\
-	 	fchmod.2			\
-	 	fchmodat.2			\
-	 	fchown.2			\
-	 	fchownat.2			\
-	 	fchroot.2			\
-	 	fork1.2				\
-	 	forkall.2			\
-	 	forkallx.2			\
-	 	forkx.2				\
-	 	fstat.2				\
-	 	fstatat.2			\
-	 	fstatvfs.2			\
-	 	futimesat.2			\
+		_exit.2				\
+		_lwp_cond_broadcast.2		\
+		_lwp_cond_reltimedwait.2	\
+		_lwp_cond_timedwait.2		\
+		_lwp_continue.2			\
+		_lwp_mutex_trylock.2		\
+		_lwp_mutex_unlock.2		\
+		_lwp_sema_init.2		\
+		_lwp_sema_post.2		\
+		_lwp_sema_trywait.2		\
+		execl.2				\
+		execle.2			\
+		execlp.2			\
+		execv.2				\
+		execve.2			\
+		execvp.2			\
+		faccessat.2			\
+		facl.2				\
+		fchdir.2			\
+		fchmod.2			\
+		fchmodat.2			\
+		fchown.2			\
+		fchownat.2			\
+		fchroot.2			\
+		fork1.2				\
+		forkall.2			\
+		forkallx.2			\
+		forkx.2				\
+		fstat.2				\
+		fstatat.2			\
+		fstatvfs.2			\
+		futimesat.2			\
 		futimens.2			\
-	 	getaudit_addr.2			\
-	 	getegid.2			\
-	 	geteuid.2			\
-	 	getgid.2			\
-	 	getpgid.2			\
-	 	getpgrp.2			\
-	 	getpmsg.2			\
-	 	getppid.2			\
-	 	getprojid.2			\
-	 	getrctl.2			\
-	 	gettaskid.2			\
-	 	intro.2				\
-	 	lchown.2			\
+		getaudit_addr.2			\
+		getegid.2			\
+		geteuid.2			\
+		getgid.2			\
+		getpgid.2			\
+		getpgrp.2			\
+		getpmsg.2			\
+		getppid.2			\
+		getprojid.2			\
+		getrctl.2			\
+		gettaskid.2			\
+		intro.2				\
+		lchown.2			\
 		linkat.2			\
-	 	lstat.2				\
+		lstat.2				\
 		mkdirat.2			\
 		mknodat.2			\
-	 	openat.2			\
-	 	pathconf.2			\
+		openat.2			\
+		pathconf.2			\
 		pipe2.2				\
 		ppoll.2				\
-	 	pread.2				\
+		pread.2				\
 		preadv.2			\
-	 	pset_assign.2			\
-	 	pset_destroy.2			\
-	 	pset_getattr.2			\
-	 	putacct.2			\
-	 	putpmsg.2			\
-	 	pwrite.2			\
+		pset_assign.2			\
+		pset_destroy.2			\
+		pset_getattr.2			\
+		putacct.2			\
+		putpmsg.2			\
+		pwrite.2			\
 		pwritev.2			\
 		readlinkat.2			\
-	 	readv.2				\
-	 	renameat.2			\
-	 	sbrk.2				\
-	 	semtimedop.2			\
-	 	setaudit.2			\
-	 	setaudit_addr.2			\
-	 	setauid.2			\
-	 	setcontext.2			\
-	 	setegid.2			\
-	 	seteuid.2			\
-	 	setgid.2			\
-	 	setgroups.2			\
-	 	setitimer.2			\
-	 	setpflags.2			\
-	 	setppriv.2			\
-	 	setrlimit.2			\
-	 	setustack.2			\
-	 	shmat.2				\
-	 	shmdt.2				\
-	 	sigsendset.2			\
+		readv.2				\
+		renameat.2			\
+		sbrk.2				\
+		semtimedop.2			\
+		setaudit.2			\
+		setaudit_addr.2			\
+		setauid.2			\
+		setcontext.2			\
+		setegid.2			\
+		seteuid.2			\
+		setgid.2			\
+		setgroups.2			\
+		setitimer.2			\
+		setpflags.2			\
+		setppriv.2			\
+		setrlimit.2			\
+		setustack.2			\
+		shmat.2				\
+		shmdt.2				\
+		sigsendset.2			\
 		symlinkat.2			\
-	 	umount2.2			\
-	 	unlinkat.2			\
+		umount2.2			\
+		unlinkat.2			\
 		utimensat.2			\
-	 	vforkx.2			\
-	 	wracct.2			\
-	 	writev.2
+		vforkx.2			\
+		wracct.2			\
+		writev.2
 
 intro.2				:= LINKSRC = Intro.2
 
diff --git a/usr/src/man/man2/getrandom.2 b/usr/src/man/man2/getrandom.2
new file mode 100644
index 0000000000..9ced3a3cb7
--- /dev/null
+++ b/usr/src/man/man2/getrandom.2
@@ -0,0 +1,134 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2018 Joyent, Inc.
+.\"
+.Dd "November 6, 2018"
+.Dt GETRANDOM 2
+.Os
+.Sh NAME
+.Nm getrandom
+.Nd get random numbers
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/random.h
+.Ft ssize_t
+.Fo getrandom
+.Fa "void *bufp"
+.Fa "size_t buflen"
+.Fa "unsigned int flags"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn getrandom
+function is used to retrieve random and pseudo-random numbers from the
+operating system.
+.Pp
+By default, the
+.Fn getrandom
+function will read up to
+.Fa buflen
+bytes of pseudo-random data into
+.Fa bufp .
+Pseudo-random data will be retrieved from the same source that provides
+data to
+.Pa /dev/urandom .
+The
+.Fn getrandom
+function may return less data than was requested in
+.Fa buflen .
+This can happen because of interrupts from signals, availability of
+data, or because the request was too large.
+Callers must always check to see how much data was actually returned.
+.Pp
+The following values may be bitwise-ORed together in the
+.Fa flags
+argument to modify the behavior of the function:
+.Bl -tag -width Dv
+.It Dv GRND_NONBLOCK
+Instead of blocking, return immediately if data is not available.
+If no data was obtained,
+.Er EAGAIN
+will be set in
+.Va errno .
+Otherwise, less data will be returned than requested.
+.It Dv GRND_RANDOM
+Use the same source of random data as reading from
+.Pa /dev/random ,
+instead of
+.Pa /dev/urandom .
+.El
+.Pp
+The
+.Fn getrandom
+function is intended to eliminate the need to explicitly call
+.Xr open 2
+and
+.Xr read 2
+on
+.Pa /dev/random
+or
+.Pa /dev/urandom .
+This eliminates the need to have the character devices available or
+cases where a program may not have an available file descriptor.
+For other uses,
+.Xr arc4random 3C
+may be a better interface.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn getrandom
+function returns the number of bytes written into
+.Fa bufp .
+Otherwise,
+.Sy -1
+is returned and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+The
+.Fn getrandom
+function will fail if:
+.Bl -tag -width Er
+.It Er EAGAIN
+The
+.Fn getrandom
+function would have blocked and
+.Dv GRND_NONBLOCK
+flag was set.
+.It Er EFAULT
+The
+.Fa bufp
+argument points to an illegal address.
+.It Er EINAVL
+An invalid value was passed in
+.Fa flags .
+.It Er EINTR
+A signal was caught during the operation and no data was transferred.
+.It Er EIO
+An internal error occurred with the corresponding
+.Xr random 7D
+device.
+.El
+.Sh INTERFACE STABILITY
+.Sy Committed
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr open 2 ,
+.Xr read 2 ,
+.Xr arc4random 3C ,
+.Xr random 7D
+.Sh STANDARDS
+The
+.Fn getrandom
+function is non-standard.
+It originally appeared in Linux.