added documentation for getcwd

[philippkeller]

I'm currently reading through Advanced Programming in the UNIX Environment which goes through most of the libc functions, explains them and does some example code. I'm trying to port the code into Rust.

I thought about adding my findings as documentation string into libc. Would that be a thing that would benefit this repo? I've added the documentation for getcwd in this PR, would that be good enough? I would add those documentation bits by bits. Is that ok or should I put as much documentation as possible in one huge PR?

[rust-highfive]

r? @alexcrichton

(rust_highfive has picked a reviewer for you, use r? to override)

[alexcrichton]

Thanks for the PR! Right now though this crate is basically just a massive header file, and we probably don't want to go down the road of adding an example for all the functions bound here.

This does seem like some good documentation, though! @steveklabnik do you have any idea perhaps on where documentation like this might go?

[posborne]

Odd timing, I've recently been thinking about docs and was just wrapping up a PR starting to improve the situation for nix (nix-rust/nix#385). As can be seen in the getcwd example, writing code that uses the libc APIs correctly can be a task.

@philippkeller It looks like we don't currently have support for getcwd in nix. Would you be interested in adding support (with docs) there? The goal of nix is to wrap the underlying libc APIs (mostly 1-to-1 but varying where required to safely capture semantics).

In general, I think it would be preferable for people to be encourage to use either std, nix, or some other more specialized crate for interacting with libc functionality rather than using libc directly. That being said, having better documentation on libc and the aforementioned advice are not mutually exclusive.

[philippkeller]

@posborne: sure! I am new to Rust though and if I would contribute code it needs some attentive pair of eyes on my PRs. If that is ok then I'd be happy to contribute. I was not really sure if the documentation really belongs here (as @alexcrichton says it's just a header file and I was not sure if that was intentional or not).

That said, @posborne if you could tell where getcwd should be living within nix, I'll retract my PR here and transform the PR into a nix PR with code and documentation.

[posborne]

That said, @posborne if you could tell where getcwd should be living within nix, I'll retract my PR here and transform the PR into a nix PR with code and documentation.

Currently, we generally map the libc header files (in this case unistd.h) to modules in the library, so unistd.rs.

[steveklabnik]

This does seem like some good documentation, though! @steveklabnik do you have any idea perhaps on where documentation like this might go?

This is a good question. I'm not sure; I'm not totally opposed to adding docs here, but can also see why we might not want to.

[philippkeller]

@posborne one question before I move this to nix: getcwd is already implemented in std which is exposed via env::current_dir. Does it make sense to have it also implemented in nix?

[posborne]

@posborne one question before I move this to nix: getcwd is already implemented in std which is exposed via env::current_dir. Does it make sense to have it also implemented in nix?

The std implementation is probably what users should use but I think it would be OK to add to nix as well for completeness/convenience (if code was using other code from Nix extensively or working in a no_std environment it might make sense).

CC @fiveop @kamalmarhubi

[fiveop]

I agree with @posborne in that we (nix) should aim for completeness, even in cases were we don't see the necessity.

And, even though I have no stake in this, I would think documentation for libc would be a bit redundant to the corresponding man pages. However, nix does change the interface sufficiently - even if only slightly - and has at least somewhat organized code, so that having its own documentation would be useful in my opinion.