Skip to content

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

Closed
@8573

Description

@8573

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?

Activity

added
O-windowsOperating system: Windows
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
on Aug 11, 2018
smmalis37

smmalis37 commented on Aug 11, 2018

@smmalis37
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

DemiMarie commented on Nov 22, 2018

@DemiMarie
Contributor

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

retep998 commented on Nov 22, 2018

@retep998
Member

OsStr may also contain zeros.

added
A-FFIArea: Foreign function interface (FFI)
T-libs-apiRelevant to the library API team, which will review and decide on the PR/issue.
C-enhancementCategory: An issue proposing an enhancement or a PR with one.
on Mar 6, 2020
added 3 commits that reference this issue on Dec 7, 2021

Rollup merge of rust-lang#91467 - ChrisDenton:confusing-os-string, r=…

c31fc42

Rollup merge of rust-lang#91467 - ChrisDenton:confusing-os-string, r=…

2d75df1

Rollup merge of rust-lang#91467 - ChrisDenton:confusing-os-string, r=…

bb8a4ab
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-FFIArea: Foreign function interface (FFI)A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-enhancementCategory: An issue proposing an enhancement or a PR with one.O-windowsOperating system: WindowsP-mediumMedium priorityT-libs-apiRelevant to the library API team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      Participants

      @steveklabnik@retep998@jonas-schievink@8573@smmalis37

      Issue actions

        I found the OsStr(ing) documentation misleading w.r.t. Windows · Issue #53261 · rust-lang/rust