1 # Japanese translations for Rust package
2 # Copyright (C) 2013 The Rust Project Developers
3 # This file is distributed under the same license as the Rust package.
4 # Automatically generated, 2013.
8 "Project-Id-Version: Rust 0.8-pre\n"
9 "POT-Creation-Date: 2013-08-10 07:44+0900\n"
10 "PO-Revision-Date: 2013-07-22 23:37+0900\n"
11 "Last-Translator: Automatically generated\n"
12 "Language-Team: none\n"
15 "Content-Type: text/plain; charset=UTF-8\n"
16 "Content-Transfer-Encoding: 8bit\n"
17 "Plural-Forms: nplurals=1; plural=0;\n"
20 #: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
21 #: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
22 #: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
23 msgid "# Introduction"
27 #: doc/tutorial.md:868 doc/tutorial-ffi.md:143
32 #: doc/tutorial-ffi.md:2
33 msgid "% Rust Foreign Function Interface Tutorial"
37 #: doc/tutorial-ffi.md:10
39 "This tutorial will use the [snappy](https://code.google.com/p/snappy/) "
40 "compression/decompression library as an introduction to writing bindings for "
41 "foreign code. Rust is currently unable to call directly into a C++ library, "
42 "but snappy includes a C interface (documented in [`snappy-c.h`](https://code."
43 "google.com/p/snappy/source/browse/trunk/snappy-c.h))."
47 #: doc/tutorial-ffi.md:13
49 "The following is a minimal example of calling a foreign function which will "
50 "compile if snappy is installed:"
54 #: doc/tutorial-ffi.md:16
55 msgid "~~~~ {.xfail-test} use std::libc::size_t;"
59 #: doc/tutorial-ffi.md:21
62 "#[link_args = \"-lsnappy\"]\n"
64 " fn snappy_max_compressed_length(source_length: size_t) -> size_t;\n"
69 #: doc/tutorial-ffi.md:27
73 " let x = unsafe { snappy_max_compressed_length(100) };\n"
74 " println(fmt!(\"max compressed length of a 100 byte buffer: %?\", x));\n"
80 #: doc/tutorial-ffi.md:31
82 "The `extern` block is a list of function signatures in a foreign library, in "
83 "this case with the platform's C ABI. The `#[link_args]` attribute is used to "
84 "instruct the linker to link against the snappy library so the symbols are "
89 #: doc/tutorial-ffi.md:37
91 "Foreign functions are assumed to be unsafe so calls to them need to be "
92 "wrapped with `unsafe {}` as a promise to the compiler that everything "
93 "contained within truly is safe. C libraries often expose interfaces that "
94 "aren't thread-safe, and almost any function that takes a pointer argument "
95 "isn't valid for all possible inputs since the pointer could be dangling, and "
96 "raw pointers fall outside of Rust's safe memory model."
100 #: doc/tutorial-ffi.md:41
102 "When declaring the argument types to a foreign function, the Rust compiler "
103 "will not check if the declaration is correct, so specifying it correctly is "
104 "part of keeping the binding correct at runtime."
108 #: doc/tutorial-ffi.md:43
109 msgid "The `extern` block can be extended to cover the entire snappy API:"
113 #: doc/tutorial-ffi.md:46
114 msgid "~~~~ {.xfail-test} use std::libc::{c_int, size_t};"
118 #: doc/tutorial-ffi.md:65
121 "#[link_args = \"-lsnappy\"]\n"
123 " fn snappy_compress(input: *u8,\n"
124 " input_length: size_t,\n"
125 " compressed: *mut u8,\n"
126 " compressed_length: *mut size_t) -> c_int;\n"
127 " fn snappy_uncompress(compressed: *u8,\n"
128 " compressed_length: size_t,\n"
129 " uncompressed: *mut u8,\n"
130 " uncompressed_length: *mut size_t) -> c_int;\n"
131 " fn snappy_max_compressed_length(source_length: size_t) -> size_t;\n"
132 " fn snappy_uncompressed_length(compressed: *u8,\n"
133 " compressed_length: size_t,\n"
134 " result: *mut size_t) -> c_int;\n"
135 " fn snappy_validate_compressed_buffer(compressed: *u8,\n"
136 " compressed_length: size_t) -> c_int;\n"
142 #: doc/tutorial-ffi.md:67
143 msgid "# Creating a safe interface"
147 #: doc/tutorial-ffi.md:71
149 "The raw C API needs to be wrapped to provide memory safety and make use of "
150 "higher-level concepts like vectors. A library can choose to expose only the "
151 "safe, high-level interface and hide the unsafe internal details."
155 #: doc/tutorial-ffi.md:76
157 "Wrapping the functions which expect buffers involves using the `vec::raw` "
158 "module to manipulate Rust vectors as pointers to memory. Rust's vectors are "
159 "guaranteed to be a contiguous block of memory. The length is number of "
160 "elements currently contained, and the capacity is the total size in elements "
161 "of the allocated memory. The length is less than or equal to the capacity."
165 #: doc/tutorial-ffi.md:84
168 "~~~~ {.xfail-test}\n"
169 "pub fn validate_compressed_buffer(src: &[u8]) -> bool {\n"
171 " snappy_validate_compressed_buffer(vec::raw::to_ptr(src), src.len() as size_t) == 0\n"
178 #: doc/tutorial-ffi.md:88
180 "The `validate_compressed_buffer` wrapper above makes use of an `unsafe` "
181 "block, but it makes the guarantee that calling it is safe for all inputs by "
182 "leaving off `unsafe` from the function signature."
186 #: doc/tutorial-ffi.md:91
188 "The `snappy_compress` and `snappy_uncompress` functions are more complex, "
189 "since a buffer has to be allocated to hold the output too."
193 #: doc/tutorial-ffi.md:96
195 "The `snappy_max_compressed_length` function can be used to allocate a vector "
196 "with the maximum required capacity to hold the compressed output. The vector "
197 "can then be passed to the `snappy_compress` function as an output parameter. "
198 "An output parameter is also passed to retrieve the true length after "
199 "compression for setting the length."
203 #: doc/tutorial-ffi.md:102
206 "~~~~ {.xfail-test}\n"
207 "pub fn compress(src: &[u8]) -> ~[u8] {\n"
209 " let srclen = src.len() as size_t;\n"
210 " let psrc = vec::raw::to_ptr(src);\n"
214 #: doc/tutorial-ffi.md:106
217 " let mut dstlen = snappy_max_compressed_length(srclen);\n"
218 " let mut dst = vec::with_capacity(dstlen as uint);\n"
219 " let pdst = vec::raw::to_mut_ptr(dst);\n"
223 #: doc/tutorial-ffi.md:113
226 " snappy_compress(psrc, srclen, pdst, &mut dstlen);\n"
227 " vec::raw::set_len(&mut dst, dstlen as uint);\n"
235 #: doc/tutorial-ffi.md:116
237 "Decompression is similar, because snappy stores the uncompressed size as "
238 "part of the compression format and `snappy_uncompressed_length` will "
239 "retrieve the exact buffer size required."
243 #: doc/tutorial-ffi.md:122
246 "~~~~ {.xfail-test}\n"
247 "pub fn uncompress(src: &[u8]) -> Option<~[u8]> {\n"
249 " let srclen = src.len() as size_t;\n"
250 " let psrc = vec::raw::to_ptr(src);\n"
254 #: doc/tutorial-ffi.md:125
257 " let mut dstlen: size_t = 0;\n"
258 " snappy_uncompressed_length(psrc, srclen, &mut dstlen);\n"
262 #: doc/tutorial-ffi.md:128
265 " let mut dst = vec::with_capacity(dstlen as uint);\n"
266 " let pdst = vec::raw::to_mut_ptr(dst);\n"
270 #: doc/tutorial-ffi.md:138
273 " if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 {\n"
274 " vec::raw::set_len(&mut dst, dstlen as uint);\n"
277 " None // SNAPPY_INVALID_INPUT\n"
285 #: doc/tutorial-ffi.md:141
287 "For reference, the examples used here are also available as an [library on "
288 "GitHub](https://github.com/thestinger/rust-snappy)."
292 #: doc/tutorial-ffi.md:147
294 "Foreign libraries often hand off ownership of resources to the calling code, "
295 "which should be wrapped in a destructor to provide safety and guarantee "
300 #: doc/tutorial-ffi.md:150
302 "A type with the same functionality as owned boxes can be implemented by "
303 "wrapping `malloc` and `free`:"
307 #: doc/tutorial-ffi.md:156
309 "~~~~ use std::cast; use std::libc::{c_void, size_t, malloc, free}; use std::"
310 "ptr; use std::unstable::intrinsics;"
314 #: doc/tutorial-ffi.md:161
317 "// a wrapper around the handle returned by the foreign code\n"
318 "pub struct Unique<T> {\n"
319 " priv ptr: *mut T\n"
324 #: doc/tutorial-ffi.md:172
327 "impl<T: Send> Unique<T> {\n"
328 " pub fn new(value: T) -> Unique<T> {\n"
330 " let ptr = malloc(std::sys::size_of::<T>() as size_t) as *mut T;\n"
331 " assert!(!ptr::is_null(ptr));\n"
332 " // `*ptr` is uninitialized, and `*ptr = value` would attempt to destroy it\n"
333 " intrinsics::move_val_init(&mut *ptr, value);\n"
334 " Unique{ptr: ptr}\n"
340 #: doc/tutorial-ffi.md:177
343 " // the 'r lifetime results in the same semantics as `&*x` with ~T\n"
344 " pub fn borrow<'r>(&'r self) -> &'r T {\n"
345 " unsafe { cast::copy_lifetime(self, &*self.ptr) }\n"
350 #: doc/tutorial-ffi.md:183
353 " // the 'r lifetime results in the same semantics as `&mut *x` with ~T\n"
354 " pub fn borrow_mut<'r>(&'r mut self) -> &'r mut T {\n"
355 " unsafe { cast::copy_mut_lifetime(self, &mut *self.ptr) }\n"
361 #: doc/tutorial-ffi.md:195
364 "#[unsafe_destructor]\n"
365 "impl<T: Send> Drop for Unique<T> {\n"
366 " fn drop(&self) {\n"
368 " let x = intrinsics::init(); // dummy value to swap in\n"
369 " // moving the object out is needed to call the destructor\n"
370 " ptr::replace_ptr(self.ptr, x);\n"
371 " free(self.ptr as *c_void)\n"
378 #: doc/tutorial-ffi.md:202
381 "// A comparison between the built-in ~ and this reimplementation\n"
386 " } // `x` is freed here\n"
390 #: doc/tutorial-ffi.md:209
394 " let mut y = Unique::new(5);\n"
395 " *y.borrow_mut() = 10;\n"
396 " } // `y` is freed here\n"
402 #: doc/tutorial-ffi.md:211
407 #: doc/tutorial-ffi.md:215
409 "In addition to the `#[link_args]` attribute for explicitly passing arguments "
410 "to the linker, an `extern mod` block will pass `-lmodname` to the linker by "
411 "default unless it has a `#[nolink]` attribute applied."
415 #: doc/tutorial-ffi.md:217
416 msgid "# Unsafe blocks"
420 #: doc/tutorial-ffi.md:221
422 "Some operations, like dereferencing unsafe pointers or calling functions "
423 "that have been marked unsafe are only allowed inside unsafe blocks. Unsafe "
424 "blocks isolate unsafety and are a promise to the compiler that the unsafety "
425 "does not leak out of the block."
429 #: doc/tutorial-ffi.md:224
431 "Unsafe functions, on the other hand, advertise it to the world. An unsafe "
432 "function is written like this:"
436 #: doc/tutorial-ffi.md:228
437 msgid "~~~~ unsafe fn kaboom(ptr: *int) -> int { *ptr } ~~~~"
441 #: doc/tutorial-ffi.md:230
443 "This function can only be called from an `unsafe` block or another `unsafe` "
448 #: doc/tutorial-ffi.md:232
449 msgid "# Accessing foreign globals"
453 #: doc/tutorial-ffi.md:236
455 "Foreign APIs often export a global variable which could do something like "
456 "track global state. In order to access these variables, you declare them in "
457 "`extern` blocks with the `static` keyword:"
461 #: doc/tutorial-ffi.md:239
462 msgid "~~~{.xfail-test} use std::libc;"
466 #: doc/tutorial-ffi.md:244
469 "#[link_args = \"-lreadline\"]\n"
471 " static rl_readline_version: libc::c_int;\n"
476 #: doc/tutorial-ffi.md:250
480 " println(fmt!(\"You have readline version %d installed.\",\n"
481 " rl_readline_version as int));\n"
487 #: doc/tutorial-ffi.md:254
489 "Alternatively, you may need to alter global state provided by a foreign "
490 "interface. To do this, statics can be declared with `mut` so rust can mutate "
495 #: doc/tutorial-ffi.md:258
496 msgid "~~~{.xfail-test} use std::libc; use std::ptr;"
500 #: doc/tutorial-ffi.md:263
503 "#[link_args = \"-lreadline\"]\n"
505 " static mut rl_prompt: *libc::c_char;\n"
510 #: doc/tutorial-ffi.md:272
514 " do \"[my-awesome-shell] $\".as_c_str |buf| {\n"
515 " unsafe { rl_prompt = buf; }\n"
516 " // get a line, process it\n"
517 " unsafe { rl_prompt = ptr::null(); }\n"
524 #: doc/tutorial-ffi.md:274
525 msgid "# Foreign calling conventions"
529 #: doc/tutorial-ffi.md:279
531 "Most foreign code exposes a C ABI, and Rust uses the platform's C calling "
532 "convention by default when calling foreign functions. Some foreign "
533 "functions, most notably the Windows API, use other calling conventions. Rust "
534 "provides the `abi` attribute as a way to hint to the compiler which calling "
539 #: doc/tutorial-ffi.md:288
543 "#[cfg(target_os = \"win32\")]\n"
544 "#[abi = \"stdcall\"]\n"
545 "#[link_name = \"kernel32\"]\n"
547 " fn SetEnvironmentVariableA(n: *u8, v: *u8) -> int;\n"
553 #: doc/tutorial-ffi.md:292
555 "The `abi` attribute applies to a foreign module (it cannot be applied to a "
556 "single function within a module), and must be either `\"cdecl\"` or `"
557 "\"stdcall\"`. The compiler may eventually support other calling conventions."
561 #: doc/tutorial-ffi.md:294
562 msgid "# Interoperability with foreign code"
566 #: doc/tutorial-ffi.md:298
568 "Rust guarantees that the layout of a `struct` is compatible with the "
569 "platform's representation in C. A `#[packed]` attribute is available, which "
570 "will lay out the struct members without padding. However, there are "
571 "currently no guarantees about the layout of an `enum`."
575 #: doc/tutorial-ffi.md:305
577 "Rust's owned and managed boxes use non-nullable pointers as handles which "
578 "point to the contained object. However, they should not be manually created "
579 "because they are managed by internal allocators. Borrowed pointers can "
580 "safely be assumed to be non-nullable pointers directly to the type. However, "
581 "breaking the borrow checking or mutability rules is not guaranteed to be "
582 "safe, so prefer using raw pointers (`*`) if that's needed because the "
583 "compiler can't make as many assumptions about them."
587 #: doc/tutorial-ffi.md:310
589 "Vectors and strings share the same basic memory layout, and utilities are "
590 "available in the `vec` and `str` modules for working with C APIs. Strings "
591 "are terminated with `\\0` for interoperability with C, but it should not be "
592 "assumed because a slice will not always be nul-terminated. Instead, the "
593 "`str::as_c_str` function should be used."
597 #: doc/tutorial-ffi.md:312
599 "The standard library includes type aliases and function definitions for the "
600 "C standard library in the `libc` module, and Rust links against `libc` and "