Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

I found the OsStr(ing) documentation misleading w.r.t. Windows #53261

Closed
8573 opened this issue Aug 11, 2018 · 3 comments · Fixed by #91467
Closed

I found the OsStr(ing) documentation misleading w.r.t. Windows #53261

8573 opened this issue Aug 11, 2018 · 3 comments · Fixed by #91467
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools A-FFI Area: Foreign function interface (FFI) C-enhancement Category: An issue proposing an enhancement or a PR with one. O-windows Operating system: Windows P-medium Medium priority T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.

Comments

@8573
Copy link

8573 commented Aug 11, 2018

The documentation for std::ffi::OsString says—

On Windows, [platform-native] strings are often arbitrary sequences of non-zero 16-bit values, interpreted as UTF-16 when it is valid to do so.

The documentation for std::ffi § "Representations of non-Rust strings" says—

  • OsString represents an owned string in whatever representation the operating system prefers. [...]
  • OsStr represents a borrowed reference to a string in a format that can be passed to the operating system. [...]

These statements led me to understand that—

  • on Microsoft Windows, an OsString would represent its text as "arbitrary sequences of non-zero 16-bit values", and not as UTF-8, and thus
  • on Windows, an OsStr would reference such a non-UTF-8 sequence, and thus
  • OsStr::to_str — which returns an Optional &str that (by my imperfect understanding of Rust reference rules) would have to reference the same thing as the OsStr — almost always would return None on Windows (except for, e.g., empty strings), because a Windows string could not validly be read as a Rust str.

However, @retep998 tells me that—

  • "OsStr::to_str on Windows will succeed most of the time",
  • OsString stores its text in WTF-8 on Windows, and
  • it's more accurate [than what the std::ffi documentation says] to say that OsStr represents an owned string in a representation capable of handling any string received from the operating system
    not necessarily the same encoding as what the operating system uses, but it can losslessly transcode back and forth

Was my misinterpretation of the documentation unreasonable? If not, could the documentation be clarified on this point?

@retep998 retep998 added O-windows Operating system: Windows A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools labels Aug 11, 2018
@smmalis37
Copy link
Contributor

Agreed on pretty much all points here. In addition, it would be really useful to have some guidance on the best way to convert an OsStr(ing) to an LPWSTR so that it can be actually used with windows apis. Either here or in winapi-rs, not sure where the best fit would be.

@DemiMarie
Copy link
Contributor

DemiMarie commented Nov 22, 2018

I would like to be able to losslessly transcode between a UNICODE_STRING and an std::ffi::OsStr. A UNICODE_STRING may contain zeros, however.

@retep998
Copy link
Member

OsStr may also contain zeros.

@steveklabnik steveklabnik added the P-medium Medium priority label Dec 27, 2018
@jonas-schievink jonas-schievink added A-FFI Area: Foreign function interface (FFI) T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. C-enhancement Category: An issue proposing an enhancement or a PR with one. labels Mar 6, 2020
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Dec 7, 2021
…Mark-Simulacrum

Emphasise that an OsStr[ing] is not necessarily a platform string

Fixes rust-lang#53261

Since that issue was filed, rust-lang#56141 added a further clarification to the `OsString` docs. However the ffi docs may still leave the impression that an `OsStr` is in the platform native form. This PR aims to further emphasise that an `OsStr` is not necessarily a platform string.
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Dec 8, 2021
…Mark-Simulacrum

Emphasise that an OsStr[ing] is not necessarily a platform string

Fixes rust-lang#53261

Since that issue was filed, rust-lang#56141 added a further clarification to the `OsString` docs. However the ffi docs may still leave the impression that an `OsStr` is in the platform native form. This PR aims to further emphasise that an `OsStr` is not necessarily a platform string.
@bors bors closed this as completed in bb8a4ab Dec 8, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools A-FFI Area: Foreign function interface (FFI) C-enhancement Category: An issue proposing an enhancement or a PR with one. O-windows Operating system: Windows P-medium Medium priority T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants