crypto primitives: added text on getrandom

en-US/Tasks-Cryptography.xml

@@ -85,6 +85,9 @@
       <listitem>
 	<para><function>os.urandom</function> in Python</para>
       </listitem>
+      <listitem>
+	<para>The <function>getrandom</function> system call</para>
+      </listitem>
       <listitem>
 	<para>Reading from the <filename>/dev/urandom</filename>
 	  character device</para>
@@ -109,6 +112,21 @@
 	using these functions.
       </para>
     </important>
+    <important>
+      <title>Difficult to use API</title>
+      <para>
+	The <function>getrandom</function> system call has three-state
+	return values, hence requires careful error checking.
+      </para>
+      <para>
+	It was introduced in Linux kernel 3.17, but as of glibc 2.22 no API wrappers are
+	provided. As such one can only use it via the syscall interface
+	as <function>syscall(SYS_getrandom, (void*)dest, (size_t)size, (unsigned int)0)</function>.
+	For portable code targetting older kernel versions one has to check 
+	for the function being	available on run-time, and switch to another
+	facility if the running kernel doesn't support this call.
+      </para>
+    </important>
     <para>
       Other sources of randomness should be considered predictable.
     </para>