---

yaml
---
r: 30338
b: refs/heads/incoming
c: 4e515c1
h: refs/heads/master
v: v3

Author: pcwalton

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
-refs/heads/incoming: 1c9c32782d7dddadfbb9dd9dd149b33e28308439
+refs/heads/incoming: 4e515c14af8598f5e0d8e62847741523e7c14ba5
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/doc/tutorial-ffi.md

@@ -0,0 +1,240 @@
+# Interacting with foreign code
+
+One of Rust's aims, as a system programming language, is to
+interoperate well with C code.
+
+We'll start with an example. It's a bit bigger than usual, and
+contains a number of new concepts. We'll go over it one piece at a
+time.
+
+This is a program that uses OpenSSL's `SHA1` function to compute the
+hash of its first command-line argument, which it then converts to a
+hexadecimal string and prints to standard output. If you have the
+OpenSSL libraries installed, it should 'just work'.
+
+~~~~ {.xfail-test}
+use std;
+import libc::c_uint;
+
+extern mod crypto {
+    fn SHA1(src: *u8, sz: c_uint, out: *u8) -> *u8;
+}
+
+fn as_hex(data: ~[u8]) -> ~str {
+    let mut acc = ~"";
+    for data.each |byte| { acc += fmt!("%02x", byte as uint); }
+    return acc;
+}
+
+fn sha1(data: ~str) -> ~str unsafe {
+    let bytes = str::to_bytes(data);
+    let hash = crypto::SHA1(vec::unsafe::to_ptr(bytes),
+                            vec::len(bytes) as c_uint, ptr::null());
+    return as_hex(vec::unsafe::from_buf(hash, 20u));
+}
+
+fn main(args: ~[~str]) {
+    io::println(sha1(args[1]));
+}
+~~~~
+
+## Foreign modules
+
+Before we can call `SHA1`, we have to declare it. That is what this
+part of the program is responsible for:
+
+~~~~ {.xfail-test}
+extern mod crypto {
+    fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8;
+}
+~~~~
+
+An `extern` module declaration containing function signatures introduces
+the functions listed as _foreign functions_, that are implemented in some
+other language (usually C) and accessed through Rust's foreign function
+interface (FFI). An extern module like this is called a foreign module, and
+implicitly tells the compiler to link with a library with the same name as
+the module, and that it will find the foreign functions in that library.
+
+In this case, it'll change the name `crypto` to a shared library name
+in a platform-specific way (`libcrypto.so` on Linux, for example), and
+link that in. If you want the module to have a different name from the
+actual library, you can use the `"link_name"` attribute, like:
+
+~~~~ {.xfail-test}
+#[link_name = "crypto"]
+extern mod something {
+    fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8;
+}
+~~~~
+
+## Foreign calling conventions
+
+Most foreign code will be C code, which usually uses the `cdecl` calling
+convention, so that is what Rust uses by default when calling foreign
+functions. Some foreign functions, most notably the Windows API, use other
+calling conventions, so Rust provides a way to hint to the compiler which
+is expected by using the `"abi"` attribute:
+
+~~~~
+#[cfg(target_os = "win32")]
+#[abi = "stdcall"]
+extern mod kernel32 {
+    fn SetEnvironmentVariableA(n: *u8, v: *u8) -> int;
+}
+~~~~
+
+The `"abi"` attribute applies to a foreign module (it can not be applied
+to a single function within a module), and must be either `"cdecl"`
+or `"stdcall"`. Other conventions may be defined in the future.
+
+## Unsafe pointers
+
+The foreign `SHA1` function is declared to take three arguments, and
+return a pointer.
+
+~~~~ {.xfail-test}
+# extern mod crypto {
+fn SHA1(src: *u8, sz: libc::c_uint, out: *u8) -> *u8;
+# }
+~~~~
+
+When declaring the argument types to a foreign function, the Rust
+compiler has no way to check whether your declaration is correct, so
+you have to be careful. If you get the number or types of the
+arguments wrong, you're likely to get a segmentation fault. Or,
+probably even worse, your code will work on one platform, but break on
+another.
+
+In this case, `SHA1` is defined as taking two `unsigned char*`
+arguments and one `unsigned long`. The rust equivalents are `*u8`
+unsafe pointers and an `uint` (which, like `unsigned long`, is a
+machine-word-sized type).
+
+Unsafe pointers can be created through various functions in the
+standard lib, usually with `unsafe` somewhere in their name. You can
+dereference an unsafe pointer with `*` operator, but use
+caution—unlike Rust's other pointer types, unsafe pointers are
+completely unmanaged, so they might point at invalid memory, or be
+null pointers.
+
+## Unsafe blocks
+
+The `sha1` function is the most obscure part of the program.
+
+~~~~
+# mod crypto { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8 { out } }
+# fn as_hex(data: ~[u8]) -> ~str { ~"hi" }
+fn sha1(data: ~str) -> ~str {
+    unsafe {
+        let bytes = str::to_bytes(data);
+        let hash = crypto::SHA1(vec::unsafe::to_ptr(bytes),
+                                vec::len(bytes), ptr::null());
+        return as_hex(vec::unsafe::from_buf(hash, 20u));
+    }
+}
+~~~~
+
+Firstly, what does the `unsafe` keyword at the top of the function
+mean? `unsafe` is a block modifier—it declares the block following it
+to be known to be unsafe.
+
+Some operations, like dereferencing unsafe pointers or calling
+functions that have been marked unsafe, are only allowed inside unsafe
+blocks. With the `unsafe` keyword, you're telling the compiler 'I know
+what I'm doing'. The main motivation for such an annotation is that
+when you have a memory error (and you will, if you're using unsafe
+constructs), you have some idea where to look—it will most likely be
+caused by some unsafe code.
+
+Unsafe blocks isolate unsafety. Unsafe functions, on the other hand,
+advertise it to the world. An unsafe function is written like this:
+
+~~~~
+unsafe fn kaboom() { ~"I'm harmless!"; }
+~~~~
+
+This function can only be called from an unsafe block or another
+unsafe function.
+
+## Pointer fiddling
+
+The standard library defines a number of helper functions for dealing
+with unsafe data, casting between types, and generally subverting
+Rust's safety mechanisms.
+
+Let's look at our `sha1` function again.
+
+~~~~
+# mod crypto { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8 { out } }
+# fn as_hex(data: ~[u8]) -> ~str { ~"hi" }
+# fn x(data: ~str) -> ~str {
+# unsafe {
+let bytes = str::to_bytes(data);
+let hash = crypto::SHA1(vec::unsafe::to_ptr(bytes),
+                        vec::len(bytes), ptr::null());
+return as_hex(vec::unsafe::from_buf(hash, 20u));
+# }
+# }
+~~~~
+
+The `str::to_bytes` function is perfectly safe: it converts a string to
+a `[u8]`. This byte array is then fed to `vec::unsafe::to_ptr`, which
+returns an unsafe pointer to its contents.
+
+This pointer will become invalid as soon as the vector it points into
+is cleaned up, so you should be very careful how you use it. In this
+case, the local variable `bytes` outlives the pointer, so we're good.
+
+Passing a null pointer as the third argument to `SHA1` makes it use a
+static buffer, and thus save us the effort of allocating memory
+ourselves. `ptr::null` is a generic function that will return an
+unsafe null pointer of the correct type (Rust generics are awesome
+like that—they can take the right form depending on the type that they
+are expected to return).
+
+Finally, `vec::unsafe::from_buf` builds up a new `[u8]` from the
+unsafe pointer that was returned by `SHA1`. SHA1 digests are always
+twenty bytes long, so we can pass `20u` for the length of the new
+vector.
+
+## Passing structures
+
+C functions often take pointers to structs as arguments. Since Rust
+records are binary-compatible with C structs, Rust programs can call
+such functions directly.
+
+This program uses the POSIX function `gettimeofday` to get a
+microsecond-resolution timer.
+
+~~~~
+use std;
+import libc::c_ulonglong;
+
+type timeval = {mut tv_sec: c_ulonglong,
+                mut tv_usec: c_ulonglong};
+#[nolink]
+extern mod lib_c {
+    fn gettimeofday(tv: *timeval, tz: *()) -> i32;
+}
+fn unix_time_in_microseconds() -> u64 unsafe {
+    let x = {mut tv_sec: 0 as c_ulonglong, mut tv_usec: 0 as c_ulonglong};
+    lib_c::gettimeofday(ptr::addr_of(x), ptr::null());
+    return (x.tv_sec as u64) * 1000_000_u64 + (x.tv_usec as u64);
+}
+
+# fn main() { assert fmt!("%?", unix_time_in_microseconds()) != ~""; }
+~~~~
+
+The `#[nolink]` attribute indicates that there's no foreign library to
+link in. The standard C library is already linked with Rust programs.
+
+A `timeval`, in C, is a struct with two 32-bit integers. Thus, we
+define a record type with the same contents, and declare
+`gettimeofday` to take a pointer to such a record.
+
+The second argument to `gettimeofday` (the time zone) is not used by
+this program, so it simply declares it to be a pointer to the nil
+type. Since all null pointers have the same representation regardless of
+their referent type, this is safe.
+