os: implement readlink/1 on !windows (#26405)

Author: warpfork

vlib/os/os.c.v

@@ -431,6 +431,16 @@ pub fn system(cmd string) int {
 }
 
 // exists returns true if `path` (file or directory) exists.
+//
+// Note that when used on symlinks, if the target of the symlink does not exist, the behavior of this function is complex.
+// On linux, mac, and similar systems, on such a symlink, this function returns false.
+// (This may make sense, in the sense that such a path does not contain anything readable.
+// It is also the same as the libc 'access' function, and may be familiar from that regard.
+// On the other hand, this case may be surprising, since it means this function can return "false" for a path that exists enough
+// that trying to create a new file or dir there subsequently (even aside from TOCTOU issues) will fail with EEXIST.)
+// On windows systems, a symlink with a target that does not exist, this function returns true.
+// Consider using lstat() for a less ambiguous result about whether a path is occupied or not;
+// whether lstat returns any result or a "not exists" error gives a clear indication of whether the path is occupied.
 pub fn exists(path string) bool {
 	$if windows {
 		p := path.replace('/', '\\')

vlib/os/os_nix.c.v

@@ -51,6 +51,8 @@ fn C.uname(name &C.utsname) int
 
 fn C.symlink(&char, &char) int
 
+fn C.readlink(&char, &char, int) int
+
 fn C.link(&char, &char) int
 
 fn C.gethostname(&char, int) int
@@ -362,16 +364,58 @@ pub fn raw_execute(cmd string) Result {
 	return execute(cmd)
 }
 
-// symlink creates a symbolic link named target, which points to origin.
+// symlink creates a symbolic link named link_name, which points to target.
 // It returns a POSIX error message, if it can not do so.
-pub fn symlink(origin string, target string) ! {
-	res := C.symlink(&char(origin.str), &char(target.str))
+pub fn symlink(target string, link_name string) ! {
+	res := C.symlink(&char(target.str), &char(link_name.str))
 	if res == 0 {
 		return
 	}
 	return error(posix_get_error_msg(C.errno))
 }
 
+// readlink reads the target of a symbolic link.
+// It returns a POSIX error message if it can not do so.
+//
+// Note that the target of a symbolic link can be any string:
+// it is often used to point to another path, but the target is not guaranteed
+// to resolve as a path, nor to point to a path that exists.
+@[manualfree]
+pub fn readlink(path string) !string {
+	// Use a region of stack to get information into; we'll return new memory of more precise size later.
+	mut buf := [max_path_buffer_size]u8{}
+	// readlink returns the number of bytes written into buf, or -1 for errors.
+	res := C.readlink(&char(path.str), &char(&buf[0]), max_path_buffer_size)
+	if res < 0 {
+		return last_error()
+	}
+	// Common case: we got a complete read into our buffer on the stack.
+	// In this case, copy the data into a new heap-allocated string that's right-sized
+	// (we can't return memory from our stack).
+	if res < max_path_buffer_size {
+		return unsafe { (&buf[0]).vstring_with_len(res).clone() }
+	}
+	// If the number of bytes read wasn't less than as many as we said we'd accept: that means we might not have gotten a complete read.
+	// In this case, we have to start doing heap allocations, increasingly large, and simply check until we get a complete one.
+	// Whenever we do succeed: we'll return a string that refers to a subset of that possibly excessively sized buffer,
+	// because we're already on the heap and returning it is valid; and because allocating a new buffer just
+	// to save some resident memory is usually a poor trade of spending of time just to reclaim a very minor amount of space.
+	mut size := max_path_buffer_size
+	for {
+		size *= 2
+		mut buf2 := unsafe { &char(malloc_noscan(size)) }
+		res2 := C.readlink(&char(path.str), buf2, size)
+		if res2 < 0 {
+			return last_error()
+		}
+		if res2 < size {
+			return unsafe { tos(&u8(&buf2[0]), res2) }
+		}
+		unsafe { free(buf2) } // and then loop around to try again with a larger one.
+	}
+	return error('${@METHOD} unreachable code')
+}
+
 // link creates a new link (also known as a hard link) to an existing file.
 // It returns a POSIX error message, if it can not do so.
 pub fn link(origin string, target string) ! {

vlib/os/os_test.c.v

@@ -615,6 +615,34 @@ fn test_symlink() {
 	}
 }
 
+fn test_readlink() {
+	$if windows {
+		eprintln('skipping ${@METHOD} on windows, api not supported')
+		return
+	}
+	os.symlink('some_target_string', 'some_symlink')!
+	defer { os.rm('some_symlink') or { panic(err) } }
+	assert os.readlink('some_symlink')! == 'some_target_string'
+}
+
+fn test_exists_symlink_dangling() {
+	$if msvc {
+		eprintln('skipping ${@METHOD} on windows + msvc; TODO: investigate why os.lstat/1 behaves differently than for gcc/clang')
+		return
+	}
+	os.symlink('nonexistent', 'dangling_symlink') or { handle_privilege_error(err) or { return } }
+	// sanity check that the symlink truly does exist.  the lack of error alone is the check.
+	// (on linux, `.get_filetype() == os.FileType.symbolic_link` is true, but on windows, a dangling symlink is reported as a regular file.)
+	os.lstat('dangling_symlink')!
+	// the exists function says false in this scenario... on linux and linux-like systems.
+	// it says true on windows!
+	$if windows {
+		assert os.exists('dangling_symlink') == true
+	} $else {
+		assert os.exists('dangling_symlink') == false
+	}
+}
+
 fn test_is_executable_writable_readable() {
 	file_name := 'rwxfile.exe'
 	create_file(file_name)!
@@ -1026,7 +1054,6 @@ fn test_execute_fc_get_output() {
 		return
 	}
 	result := os.execute('c:\\windows\\system32\\fc.exe /?')
-	dump(result)
 	assert result.output.contains('filename')
 	assert result.exit_code == -1
 }

vlib/os/os_windows.c.v

@@ -431,6 +431,12 @@ pub fn symlink(origin string, target string) ! {
 	return error('could not symlink')
 }
 
+// readlink reads the target of a symbolic link.
+// TODO: implement this for windows too.
+pub fn readlink(path string) !string {
+	return error('${@METHOD} not yet supported on windows')
+}
+
 pub fn link(origin string, target string) ! {
 	res := C.CreateHardLinkW(target.to_wide(), origin.to_wide(), C.NULL)
 	// 1 = success, != 1 failure => https://stackoverflow.com/questions/33010440/createsymboliclink-on-windows-10