Merge branch 'master' of github.com:perl6/doc

Author: stmuk

lib/Language/nativecall.pod

@@ -297,6 +297,33 @@ to callbacks.
 
 TBD
 
+=head2 Calling into the standard library
+
+If you want to call a C function that's already loaded, either from the
+standard library or from your own program, you can pass the C<Str> type object
+as the argument to C<is native>, so C<is native(Str)>.
+
+For example on a UNIX-like operating system, you could use the following code
+to print the home directory of the current user:
+
+    use NativeCall;
+    my class PwStruct is repr('CStruct') {
+        has Str $.pw_name;
+        has Str $.pw_passwd;
+        has uint32 $.pw_uid;
+        has uint32 $.pw_gid;
+        has Str $.pw_gecos;
+        has Str $.pw_dir;
+        has Str $.pw_shell;
+    }
+    sub getuid()           returns uint32   is native(Str) {};
+    sub getpwuid(int $uid) returns PwStruct is native(Str) {};
+
+    say getpwuid(getuid()).pw_dir;
+
+Though of course C<$*HOME> is a much easier way :-)
+
+
 =head1 Exported variables
 
 Variables exported by a library -- also named "global" or "extern"