authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-12-12 16:30:22-08:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-12-23 22:15:09-08:00
log22b0eea3c0a2d2088ea6823d1de4ea5d9da6260d
treecadf1eb9e91375b662001d22eeb81dd549fe89df
parent6484101f7860988d2147b519c0c53b9fdc23b7c2

std.Io.Dir: improve realPath documentation

1 files changed, 30 insertions(+), 11 deletions(-)

lib/std/Io/Dir.zig+30-11
...@@ -789,21 +789,17 @@ pub const RealPathError = error{...@@ -789,21 +789,17 @@ pub const RealPathError = error{
789 UnrecognizedVolume,789 UnrecognizedVolume,
790} || PathNameError || Io.Cancelable || Io.UnexpectedError;790} || PathNameError || Io.Cancelable || Io.UnexpectedError;
791791
792/// This function returns the canonicalized absolute pathname of `pathname`792/// This function returns the canonicalized absolute path name of `sub_path`
793/// relative to this `Dir`. If `pathname` is absolute, ignores this `Dir`793/// relative to this `Dir`. If `sub_path` is absolute, ignores this `Dir`
794/// handle and returns the canonicalized absolute pathname of `pathname`794/// handle and returns the canonicalized absolute pathname of `sub_path`
795/// argument.795/// argument.
796///796///
797/// On Windows, `sub_path` should be encoded as [WTF-8](https://wtf-8.codeberg.page/).797/// This function is not universally supported by all platforms, and using this
798/// On other platforms, `sub_path` is an opaque sequence of bytes with no particular encoding.798/// function can lead to unnecessary failures and race conditions.
799/// On Windows, the result is encoded as [WTF-8](https://wtf-8.codeberg.page/).
800/// On other platforms, the result is an opaque sequence of bytes with no particular encoding.
801///
802/// This function is not universally supported by all platforms. Currently
803/// supported hosts are: Linux, macOS, and Windows.
804///799///
805/// See also:800/// See also:
806/// * `realPathAlloc`.801/// * `realPathAlloc`.
802/// * `realPathAbsolute`.
807pub fn realPath(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPathError!usize {803pub fn realPath(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPathError!usize {
808 return io.vtable.dirRealPath(io.userdata, dir, sub_path, out_buffer);804 return io.vtable.dirRealPath(io.userdata, dir, sub_path, out_buffer);
809}805}
...@@ -811,18 +807,41 @@ pub fn realPath(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPa...@@ -811,18 +807,41 @@ pub fn realPath(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPa
811pub const RealPathAllocError = RealPathError || Allocator.Error;807pub const RealPathAllocError = RealPathError || Allocator.Error;
812808
813/// Same as `realPath` except allocates result.809/// Same as `realPath` except allocates result.
810///
811/// This function is not universally supported by all platforms, and using this
812/// function can lead to unnecessary failures and race conditions.
813///
814/// See also:
815/// * `realPath`.
816/// * `realPathAbsolute`.
814pub fn realPathAlloc(dir: Dir, io: Io, sub_path: []const u8, allocator: Allocator) RealPathAllocError![:0]u8 {817pub fn realPathAlloc(dir: Dir, io: Io, sub_path: []const u8, allocator: Allocator) RealPathAllocError![:0]u8 {
815 var buffer: [max_path_bytes]u8 = undefined;818 var buffer: [max_path_bytes]u8 = undefined;
816 const n = try realPath(dir, io, sub_path, &buffer);819 const n = try realPath(dir, io, sub_path, &buffer);
817 return allocator.dupeZ(u8, buffer[0..n]);820 return allocator.dupeZ(u8, buffer[0..n]);
818}821}
819822
823/// Same as `realPath` except `absolute_path` is asserted to be an absolute
824/// path.
825///
826/// This function is not universally supported by all platforms, and using this
827/// function can lead to unnecessary failures and race conditions.
828///
829/// See also:
830/// * `realPath`.
831/// * `realPathAlloc`.
820pub fn realPathAbsolute(io: Io, absolute_path: []const u8, out_buffer: []u8) RealPathError!usize {832pub fn realPathAbsolute(io: Io, absolute_path: []const u8, out_buffer: []u8) RealPathError!usize {
821 assert(path.isAbsolute(absolute_path));833 assert(path.isAbsolute(absolute_path));
822 return io.vtable.dirRealPath(io.userdata, .cwd(), absolute_path, out_buffer);834 return io.vtable.dirRealPath(io.userdata, .cwd(), absolute_path, out_buffer);
823}835}
824836
825/// Same as `realPathAbsolute` except allocates result.837/// Same as `realPathAbsolute` except allocates result.
838///
839/// This function is not universally supported by all platforms, and using this
840/// function can lead to unnecessary failures and race conditions.
841///
842/// See also:
843/// * `realPathAbsolute`.
844/// * `realPath`.
826pub fn realPathAbsoluteAlloc(io: Io, absolute_path: []const u8, allocator: Allocator) RealPathAllocError![:0]u8 {845pub fn realPathAbsoluteAlloc(io: Io, absolute_path: []const u8, allocator: Allocator) RealPathAllocError![:0]u8 {
827 var buffer: [max_path_bytes]u8 = undefined;846 var buffer: [max_path_bytes]u8 = undefined;
828 const n = try realPathAbsolute(io, absolute_path, &buffer);847 const n = try realPathAbsolute(io, absolute_path, &buffer);