Export stat! and add it to the manual

[dalum]

This is a follow-up to #46410, which was merged before these new symbols were exported and added to the manual. This PR does that.

[jakobnissen]

I know stat! is implicitly tested by testing stat, but perhaps add a test of what happens when e.g. a user passes a vector of the wrong size, or wrong element type?

[dalum]

The methods are concretely typed on Vector{UInt8}, so passing a vector of the wrong element type is just a method error. Because of the ccalls, a vector that's too small may cause a segfault, so that's perhaps not the best thing to put in a test. We can add a test that a too large vector allocates enough memory, but that seems superfluous. But perhaps a warning can be added to the docstring, that undefined behaviour, including Julia crashing, can result from calling stat! with a buffer that wasn't created using Base.Filesystem.get_stat_buf()?

[jakobnissen]

Perhaps it would be better to include something like

length(buffer) < STAT_BUFFER_SIZE && resize!(buffer, STAT_BUFFER_SIZE)

, if the size of the statbuffer is a compile time constant. It looks from src/sys.c like it is a compile time constant, so perhaps it would be better to have some Julia level code like

const STAT_BUFFER_SIZE = Int(ccall(:jl_sizeof_stat, Int32, ()))

and then have the conditional resize!. This would prevent exposing segfaulty code to users, while also skipping the ccall to determine the buffer size.

[dalum]

That sounds very reasonable, let me add it 😊

[rfourquet]

Then I would consider also not exposing get_buffer_stat, as users can just pass buf = UInt8[] and buf will be resized to the correct size after the first call to stat!, and instead possibly exposing Base.Filesystem.STAT_BUFFER_SIZE to allow getting the correct size at buffer creation time (with zeros(UInt8, STAT_BUFFER_SIZE)).

[dalum]

Since #50323 was merged, I updated this PR to include the reverted changes.

[KristofferC]

Just want to reiterate the comment #46410 (comment).