Better comments and a CHANGELOG entry

Author: asomers

CHANGELOG.md

@@ -6,6 +6,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 
 ### Added
+- Added `sysconf`, `pathconf`, and `fpathconf`
+  ([#630](https://github.com/nix-rust/nix/pull/630)
 - Added `sys::signal::SigAction::{ flags, mask, handler}`
   ([#611](https://github.com/nix-rust/nix/pull/609)
 - Added `nix::sys::pthread::pthread_self`

src/unistd.rs

@@ -822,9 +822,9 @@ pub fn mkstemp<P: ?Sized + NixPath>(template: &P) -> Result<(RawFd, PathBuf)> {
 }
 
 /// Variable names for `pathconf`
-// Note: POSIX 1003.1-2008 requires all of these symbols to be
-// supported, but Rust's libc does not yet define them all for all
-// platforms
+///
+/// Note: POSIX 1003.1-2008 standardizes all of these variables, but some OSes
+/// choose not to implement variables that cannot change at runtime.
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 #[repr(i32)]
 pub enum PathconfVar {
@@ -889,6 +889,8 @@ pub enum PathconfVar {
 ///     unsupported (for option variables)
 /// - `Err(x)`: an error occurred
 ///
+/// # Referencces
+///
 /// http://pubs.opengroup.org/onlinepubs/9699919799/functions/pathconf.html
 pub fn fpathconf(fd: RawFd, var: PathconfVar) -> Result<Option<c_long>> {
     let raw = unsafe {
@@ -911,12 +913,12 @@ pub fn fpathconf(fd: RawFd, var: PathconfVar) -> Result<Option<c_long>> {
 /// Returns the value of a path-dependent configurable system variable.  Most
 /// supported variables also have associated compile-time constants, but POSIX
 /// allows their values to change at runtime.  There are generally two types of
-/// pathconf variables: options and limits.  See pathconf(3) for more details.
+/// `pathconf` variables: options and limits.  See pathconf(3) for more details.
 ///
 /// # Parameters
 ///
 /// - `path`: Lookup the value of `var` for this file or directory
-/// - `var`:  The pathconf variable to lookup
+/// - `var`:  The `pathconf` variable to lookup
 ///
 /// # Returns
 ///
@@ -927,6 +929,8 @@ pub fn fpathconf(fd: RawFd, var: PathconfVar) -> Result<Option<c_long>> {
 ///     unsupported (for option variables)
 /// - `Err(x)`: an error occurred
 ///
+/// # Referencces
+///
 /// http://pubs.opengroup.org/onlinepubs/9699919799/functions/pathconf.html
 pub fn pathconf<P: ?Sized + NixPath>(path: &P, var: PathconfVar) -> Result<Option<c_long>> {
     let raw = try!(path.with_nix_path(|cstr| {
@@ -947,8 +951,9 @@ pub fn pathconf<P: ?Sized + NixPath>(path: &P, var: PathconfVar) -> Result<Optio
 }
 
 /// Variable names for `sysconf`
-// Note: All of these symbols are standardized by POSIX 1003.1-2008, but haven't
-// been implemented by all platforms.
+///
+/// Note: All of these symbols are standardized by POSIX 1003.1-2008, but haven't
+/// been implemented by all platforms.
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 #[repr(i32)]
 pub enum SysconfVar {
@@ -1229,6 +1234,8 @@ _XOPEN_VERSION = libc::_SC_XOPEN_VERSION,
 ///     unsupported (for option variables)
 /// - Err(x): an error occurred
 ///
+/// # Referencces
+///
 /// http://pubs.opengroup.org/onlinepubs/9699919799/functions/sysconf.html
 pub fn sysconf(var: SysconfVar) -> Result<Option<c_long>> {
     let raw = unsafe {

test/test_unistd.rs

@@ -221,28 +221,31 @@ execve_test_factory!(test_execvpe, execvpe, b"sh", b"sh");
 #[test]
 fn test_fpathconf_limited() {
     let f = tempfile().unwrap();
+    // AFAIK, PATH_MAX is limited on all platforms, so it makes a good test
     let path_max = fpathconf(f.as_raw_fd(), PathconfVar::PATH_MAX);
     assert!(path_max.expect("fpathconf failed").expect("PATH_MAX is unlimited") > 0);
 }
 
 #[test]
 fn test_pathconf_limited() {
+    // AFAIK, PATH_MAX is limited on all platforms, so it makes a good test
     let path_max = pathconf(".", PathconfVar::PATH_MAX);
     assert!(path_max.expect("pathconf failed").expect("PATH_MAX is unlimited") > 0);
 }
 
 #[test]
 fn test_sysconf_limited() {
+    // AFAIK, OPEN_MAX is limited on all platforms, so it makes a good test
     let open_max = sysconf(SysconfVar::OPEN_MAX);
     assert!(open_max.expect("sysconf failed").expect("OPEN_MAX is unlimited") > 0);
 }
 
-// Test sysconf with an unsupported varible
-// Note: If future versions of FreeBSD add support for this option then the test
-// must be modified.
 #[cfg(target_os = "freebsd")]
 #[test]
-fn test_sysconf_unlimited() {
+fn test_sysconf_unsupported() {
+    // I know of no sysconf variables that are unsupported everywhere, but
+    // _XOPEN_CRYPT is unsupported on FreeBSD 11.0, which is one of the platforms
+    // we test.
     let open_max = sysconf(SysconfVar::_XOPEN_CRYPT);
     assert!(open_max.expect("sysconf failed").is_none())
 }