Introduce set_errno

[PolyMeilex]

What does this PR do

This adds a way to set errno, it makes it possible to fully drop errno crate in crates that already use nix.

Checklist:

• I have read CONTRIBUTING.md
• I have written necessary tests and rustdoc comments
• A change log has been added if this PR modifies nix's API

[asomers]

How about a usage example? And FTR, what function from the errno crate does this replace? Oh, and don't worry about the test failure on DragonflyBSD; it's unrelated.

[PolyMeilex]

How about a usage example?

If you are asking for a use case, I simply noticed that fish shell depends both on nix and errno, so I digged into it and that's how I found out that nix does not have a way to set errnos.
As to why they need a way to set errno, the project is transitioning from C++ so errno is being used here and there.
But same need would arise if one is writing rust libs meant for consumption from C.

And if you are asking me to add rustdoc usage example, sure I can do that, just let me know that I misunderstood the question.

And FTR, what function from the errno crate does this replace?

Simply errno::set_errno

[asomers]

Yeah, a rustdoc example would be great. Also, you'll have to rebase to fix the CI failure.

[PolyMeilex]

Rebased, examples added to module docs, and to set and clear functions

[PolyMeilex]

I'm not sure if this should be top level function, if clear is a static method already?

Currently we have:

pub fn errno() -> i32;
pub fn set_errno(errno: Errno);

impl Errno {
    pub fn clear(); // Does the same'ish action as set but lives in diferent scope
    pub fn last() -> Errno;
}

So that's not consistent.

But moving set to a method does not seem entirely right either?

impl Errno {
    pub fn set(&self); // Like so?
    pub fn set(errno: Errno) // Or perhaps like this?
}

Personally I would just move clear to top level as well to make it consistent, but that's already part of public API, so I would rather not break it for no reason.

[asomers]

Excellent question. I agree that the current situation is inconsistent. I'm a fan of namespaces, so my preference would be:

impl Errno {
    fn set(self) {...}
    fn clear() {...}
    fn last() { ...}
}

[SteveLauC]

I'm not sure if this should be top level function, if clear is a static method already?

Currently we have:

pub fn errno() -> i32;
pub fn set_errno(errno: Errno);

impl Errno {
    pub fn clear(); // Does the same'ish action as set but lives in diferent scope
    pub fn last() -> Errno;
}

So that's not consistent.

It is indeed not consistent.

I think the following approach is ok:

impl Errno {
    pub fn set(errno: Errno) {}

So when people use it, Errno:: would just behave like a namespace.

---

For nix::errno::errno() -> i32, Maybe we should also move it to:

impl Errno {
    /// Returns the platform-specific value of errno
    pub fn last_raw() -> i32 { }
}

And nix::errno::from_i32() (consts::from_i32()) should be marked pub(crate) so that we don't expose 2 interfaces for 1 thing.

If we have last_raw(), then this function should probably be re-named as from_raw()

@asomers thoughts on this?

[asomers]

I agree with renaming errno() to Errno::last_raw. But what exactly do you want to rename from_raw, and why?

[SteveLauC]

I agree with renaming errno() to Errno::last_raw. But what exactly do you want to rename from_raw, and why?

Just for symmetry:

impl Errno {
    pub fn from_raw(raw: i32) -> Errno
    pub fn last_raw() -> i32
}

[SteveLauC]

To deprecate an interface, we do it like this.

The version of the next release will be 0.28.0.

[PolyMeilex]

To deprecate an interface, we do it like this.

The version of the next release will be 0.28.0.

Done.

Although I have no idea why the CI is failing, I can't figure out where is the code that causes this error:
EDIT: Nevermind, just had to rebase

[SteveLauC]

I agree with renaming errno() to Errno::last_raw. But what exactly do you want to rename from_raw, and why?

Just for symmetry:

impl Errno {
    pub fn from_raw(raw: i32) -> Errno
    pub fn last_raw() -> i32
}

LGTM! Thanks!

But I would like to know @asomers's view on the new APIs before merging this PR.

[SteveLauC]

Thanks!