unistd::getgrouplist: Add a note about returning an error

Author: JayH5

src/unistd.rs

@@ -1014,6 +1014,14 @@ pub fn setgroups(groups: &[Gid]) -> Result<()> {
 /// groups that `user` is a member of. The additional group `group` is also
 /// added to the list.
 ///
+/// *Note:* Although the `getgrouplist()` call does not return any specific
+/// errors on any known platforms, this implementation will return a system
+/// error of `EINVAL` if the number of groups to be fetched exceeds the
+/// `NGROUPS_MAX` sysconf value. This mimics the behaviour of `getgroups()`
+/// and `setgroups()`. Additionally, while some implementations will return a
+/// partial list of groups when `NGROUPS_MAX` is exceeded, this implementation
+/// will only ever return the complete list or else an error.
+///
 /// [Further reading](http://man7.org/linux/man-pages/man3/getgrouplist.3.html)
 pub fn getgrouplist(user: &CString, group: Gid) -> Result<Vec<Gid>> {
     let ngroups_max = match sysconf(SysconfVar::NGROUPS_MAX) {
@@ -1051,7 +1059,6 @@ pub fn getgrouplist(user: &CString, group: Gid) -> Result<Vec<Gid>> {
             let cap = groups.capacity();
             if cap >= ngroups_max as usize {
                 // We already have the largest capacity we can, give up
-                // FIXME: What error should be returned?
                 return Err(Error::invalid_argument())
             }