unistd: add docs for gethostname and tweak API

Although the underlying C API does take a pointer to a set of
characters, it is a requirement of almost every operating system
that these bytes not contain a premature NUL character or other
special characters.  In other words, you want a `&str`.  Changing
this to make the API make a bit more sense.

Signed-off-by: Paul Osborne <[email protected]>

CHANGELOG.md

@@ -64,6 +64,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - `SigFlags` in `::nix::sys::signal` has be renamed to `SigmaskHow` and its type
   has changed from `bitflags` to `enum` in order to conform to our conventions.
   ([#460](https://github.com/nix-rust/nix/pull/460))
+- `sethostname` now takes a `&str` instead of a `&[u8]` as this provides an API
+  that makes more sense in normal, correct usage of the API.
 
 ### Fixed
 - Fixed multiple issues with Unix domain sockets on non-Linux OSes

src/unistd.rs

@@ -480,7 +480,14 @@ pub fn daemon(nochdir: bool, noclose: bool) -> Result<()> {
     Errno::result(res).map(drop)
 }
 
-pub fn sethostname(name: &[u8]) -> Result<()> {
+/// Set the system host name (see
+/// [gethostname(2)](http://man7.org/linux/man-pages/man2/gethostname.2.html)).
+///
+/// Given a name, attempt to update the system host name to the given string.
+/// On some systems, the host name is limited to as few as 64 bytes.  An error
+/// will be return if the name is not valid or the current process does not have
+/// permissions to update the host name.
+pub fn sethostname(name: &str) -> Result<()> {
     // Handle some differences in type of the len arg across platforms.
     cfg_if! {
         if #[cfg(any(target_os = "dragonfly",