Rust Away Mac OS
Make sure that your Mac has a connection to the internet. Then turn on your Mac and immediately press and hold Command (⌘)-R until you see an Apple logo or other image. If you're asked to select a user you know the password for, select the user, click Next, then enter their administrator password. An OS X SDK, you can copy it off of a Mac (this part sucks) The gist above pulls the first two from Mozilla's tooltool (a content store), and requires you to provide the third yourself. Getting plain Rust code to build is pretty straightforward, but once you hit a crate with a native code dependency it gets a little tricky, hence most of the.
In this post I'll show you the code path that Rust takes inside itsstandard library when you open a file. I wanted to learn how Rusthandles system calls and errno, and all the little subtleties of thePOSIX API. This is what I learned!
When you open a file, or create a socket, or do anything else thatreturns an object that can be accessed like a file, you get a filedescriptor in the form of an int.
You get a nonnegative integer in case of success, or -1 in case of anerror. If there's an error, you look at errno, which gives you aninteger error code.
Many system calls can return EINTR, which means 'interrupted systemcall', which means that something interrupted the kernel while itwas doing your system call and it returned control to userspace, withthe syscall unfinished. For example, your process may have received aUnix signal (e.g. you send it SIGSTOP by pressing Ctrl-Z on aterminal, or you resized the terminal and your process got aSIGWINCH). Most of the time EINTR means simply that you mustretry the operation: if you Control-Z a program to suspend it, andthen fg to continue it again; and if the program was in the middleof open()ing a file, you would expect it to continue at that exactpoint and to actually open the file. Software that doesn't check forEINTR can fail in very subtle ways!
Once you have an open file descriptor, you can read from it:
... and one has to remember that if read() returns 0, it means wewere at the end-of-file; if it returns less than the number of bytesrequested it means we were close to the end of file; if this is anonblocking socket and it returns EWOULDBLOCK or EAGAIN then onemust decide to retry the operation or actually wait and try againlater.
There is a lot of buggy software written in C that tries to use thePOSIX API directly, and gets these subtleties wrong. Most programswritten in high-level languages use the I/O facilities provided bytheir language, which hopefully make things easier.
Rust makes error handling convenient and safe. If you decide toignore an error, the code looks like it is ignoring the error(e.g. you can grep for unwrap() and find lazy code). Thecode actually looks better if it doesn't ignore the error andproperly propagates it upstream (e.g. you can use the ? shortcut topropagate errors to the calling function).
Rust Away Mac Os X
I keep recommending this article on error models to people; itdiscusses POSIX-like error codes vs. exceptions vs. more modernapproaches like Haskell's and Rust's - definitely worth studying overa few of days (also, see Miguel's valiant effort to move C# I/O awayfrom exceptions for I/O errors).
So, what happens when one opens a file in Rust, from the toplevel APIdown to the system calls? Let's go down the rabbit hole.
You can open a file like this:
This does not give you a raw file descriptor; it gives you anio::Result<fs::File, io::Error>, which you must pick apart to see ifyou actually got back a File that you can operate on, or an error.
Let's look at the implementation of File::open() and File::create().
Here, OpenOptions is an auxiliary struct that implements a 'builder'pattern. Instead of passing bitflags for the variousO_CREATE/O_APPEND/etc. flags from the open(2) system call, onebuilds a struct with the desired options, and finally calls .open()on it.
So, let's look at the implementation of OpenOptions.open():
See that fs_imp::File::open()? That's what we want: it's theplatform-specific wrapper for opening files. Let's lookat its implementation for Unix:
The first line, let path = cstr(path)? tries to convert a Pathinto a nul-terminated C string. The second line calls the following:
Here, let flags = ... converts the OpenOptions we had in thebeginning to an int with bit flags.
Then, it does let fd = cvt_r (LAMBDA), and that lambda functioncalls the actual open64() from libc (a Rust wrapper for the system'slibc): it returns a file descriptor, or -1 on error. Why is thisdone in a lambda? Let's look at cvt_r():
Okay! Here f is the lambda that calls open64(); cvt_r() callsit in a loop and translates the POSIX-like result into somethingfriendly to Rust. This loop is where it handles EINTR, which getstranslated into ErrorKind::Interrupted. I suppose cvt_r() standsfor convert_retry()? Let's look atthe implementation of cvt(), which fetches the error code:
(The IsMinusOne shenanigans are just a Rust-ism to help convertmultiple integer types without a lot of as casts.)
The above means, if the POSIX-like result was -1, return an Err() fromthe last error returned by the operating system. That should surelybe errno internally, correct? Let's look atthe implementation for io::Error::last_os_error():
We don't need to look at Error::from_raw_os_error(); it's just aconversion function from an errno value into a Rust enum value.However, let's look at sys::os::errno():
Here, errno_location() is an extern function defined in GNU libc(or whatever C library your Unix uses). It returns a pointer to theactual int which is the errno thread-local variable. Since non-Ccode can't use libc's global variables directly, there needs to be away to get their addresses via function calls - that's whaterrno_location() is for.
And on Windows?
Remember the internal File.open()? This is what it lookslike on Windows:
CreateFileW() is the Windows API function to open files. Theconversion of error codes inside Error::last_os_error() happensanalogously - it calls GetLastError() from the Windows API andconverts it.
Can we not call C libraries?
The Rust/Unix code above depends on the system's libc for open() anderrno, which are entirely C constructs. Libc is what actually doesthe system calls. There are efforts to make the Rust standard librarynot use libc and use syscalls directly.
As an example, you can look atthe Rust standard library for Redox. Redox is a new operatingsystem kernel entirely written in Rust. Fun times!
Update: If you want to see what a C-less libstd would looklike, take a look at steed, an effort to reimplement Rust's libstdwithout C dependencies.
Rust is very meticulous about error handling, but it succeeds inmaking it pleasant to read. I/O functions give you back anio::Result<>, which you piece apart to see if it succeeded or got anerror.
Internally, and for each platform it supports, the Rust standardlibrary translates errno from libc into an io::ErrorKind Rustenum. The standard library also automatically handles Unix-isms likeretrying operations on EINTR.
I've been enjoying reading the Rust standard library code: ithas taught me many Rust-isms, and it's nice to see how thehairy/historical libc constructs are translated into clean Rustidioms. I hope this little trip down the rabbit hole for theopen(2) system call lets you look in other interesting places, too.
Getting started
If you're just getting started withRust and would like a more detailed walk-through, see ourgetting started page.
Windows considerations
On Windows, Rust additionally requires the C++ build tools for Visual Studio 2013 or later. The easiest way to acquire the build tools is by installing Microsoft Visual C++ Build Tools 2019 which provides just the Visual C++ build tools. Alternately, you can install Visual Studio 2019, Visual Studio 2017, Visual Studio 2015, or Visual Studio 2013 and during install select the “C++ tools.”
For further information about configuring Rust on Windows see the Windows-specific rustup documentation.
Toolchain management with rustup
Rust is installed and managed by the rustup tool. Rust has a 6-week rapid release process and supports a great number of platforms, so there are many builds of Rust available at any time. rustup manages these builds in a consistent way on every platform that Rust supports, enabling installation of Rust from the beta and nightly release channels as well as support for additional cross-compilation targets.
If you've installed rustup in the past, you can update your installation by running rustup update.
For more information see the rustup documentation.
Configuring the PATH environmentvariable
In the Rust development environment, all tools are installed to the ~/.cargo/bin%USERPROFILE%.cargobin directory, and this is where you will find the Rust toolchain, including rustc, cargo, and rustup.
Accordingly, it is customary for Rust developers to include this directory in their PATH environment variable. During installation rustup will attempt to configure the PATH. Because of differences between platforms, command shells, and bugs in rustup, the modifications to PATH may not take effect until the console is restarted, or the user is logged out, or it may not succeed at all.
If, after installation, running rustc --version in the console fails, this is the most likely reason.
Uninstall Rust
Rust Away Mac Os Update
If at any point you would like to uninstall Rust, you can run rustup self uninstall. We'll miss you though!