rustix/path/
arg.rs

Help
1//! Convenient and efficient string argument passing.
2//!
3//! This module defines the `Arg` trait and implements it for several common
4//! string types. This allows users to pass any of these string types directly
5//! to rustix APIs with string arguments, and it allows rustix to implement
6//! NUL-termination without the need for copying or dynamic allocation where
7//! possible.
8
9use crate::ffi::CStr;
10use crate::io;
11#[cfg(feature = "itoa")]
12use crate::path::DecInt;
13use crate::path::SMALL_PATH_BUFFER_SIZE;
14#[cfg(all(feature = "alloc", feature = "itoa"))]
15use alloc::borrow::ToOwned;
16use core::mem::MaybeUninit;
17use core::{ptr, slice, str};
18#[cfg(feature = "std")]
19use std::ffi::{OsStr, OsString};
20#[cfg(all(feature = "std", target_os = "hermit"))]
21use std::os::hermit::ext::ffi::{OsStrExt, OsStringExt};
22#[cfg(all(feature = "std", unix))]
23use std::os::unix::ffi::{OsStrExt, OsStringExt};
24#[cfg(all(feature = "std", target_os = "vxworks"))]
25use std::os::vxworks::ext::ffi::{OsStrExt, OsStringExt};
26#[cfg(all(feature = "std", target_os = "wasi"))]
27use std::os::wasi::ffi::{OsStrExt, OsStringExt};
28#[cfg(feature = "std")]
29use std::path::{Component, Components, Iter, Path, PathBuf};
30#[cfg(feature = "alloc")]
31use {crate::ffi::CString, alloc::borrow::Cow};
32#[cfg(feature = "alloc")]
33use {alloc::string::String, alloc::vec::Vec};
34
35/// A trait for passing path arguments.
36///
37/// This is similar to [`AsRef`]`<`[`Path`]`>`, but is implemented for more
38/// kinds of strings and can convert into more kinds of strings.
39///
40/// # Examples
41///
42/// ```
43/// # #[cfg(any(feature = "fs", feature = "net"))]
44/// use rustix::ffi::CStr;
45/// use rustix::io;
46/// # #[cfg(any(feature = "fs", feature = "net"))]
47/// use rustix::path::Arg;
48///
49/// # #[cfg(any(feature = "fs", feature = "net"))]
50/// pub fn touch<P: Arg>(path: P) -> io::Result<()> {
51///     let path = path.into_c_str()?;
52///     _touch(&path)
53/// }
54///
55/// # #[cfg(any(feature = "fs", feature = "net"))]
56/// fn _touch(path: &CStr) -> io::Result<()> {
57///     // implementation goes here
58///     Ok(())
59/// }
60/// ```
61///
62/// Users can then call `touch("foo")`, `touch(cstr!("foo"))`,
63/// `touch(Path::new("foo"))`, or many other things.
64///
65/// [`AsRef`]: std::convert::AsRef
66pub trait Arg {
67    /// Returns a view of this string as a string slice.
68    fn as_str(&self) -> io::Result<&str>;
69
70    /// Returns a potentially-lossy rendering of this string as a
71    /// `Cow<'_, str>`.
72    #[cfg(feature = "alloc")]
73    fn to_string_lossy(&self) -> Cow<'_, str>;
74
75    /// Returns a view of this string as a maybe-owned [`CStr`].
76    #[cfg(feature = "alloc")]
77    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>>;
78
79    /// Consumes `self` and returns a view of this string as a maybe-owned
80    /// [`CStr`].
81    #[cfg(feature = "alloc")]
82    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
83    where
84        Self: 'b;
85
86    /// Runs a closure with `self` passed in as a `&CStr`.
87    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
88    where
89        Self: Sized,
90        F: FnOnce(&CStr) -> io::Result<T>;
91}
92
93/// Runs a closure on `arg` where `A` is mapped to a `&CStr`
94pub fn option_into_with_c_str<T, F, A>(arg: Option<A>, f: F) -> io::Result<T>
95where
96    A: Arg + Sized,
97    F: FnOnce(Option<&CStr>) -> io::Result<T>,
98{
99    if let Some(arg) = arg {
100        arg.into_with_c_str(|p| f(Some(p)))
101    } else {
102        f(None)
103    }
104}
105
106impl Arg for &str {
107    #[inline]
108    fn as_str(&self) -> io::Result<&str> {
109        Ok(self)
110    }
111
112    #[cfg(feature = "alloc")]
113    #[inline]
114    fn to_string_lossy(&self) -> Cow<'_, str> {
115        Cow::Borrowed(self)
116    }
117
118    #[cfg(feature = "alloc")]
119    #[inline]
120    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
121        Ok(Cow::Owned(
122            CString::new(*self).map_err(|_cstr_err| io::Errno::INVAL)?,
123        ))
124    }
125
126    #[cfg(feature = "alloc")]
127    #[inline]
128    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
129    where
130        Self: 'b,
131    {
132        Ok(Cow::Owned(
133            CString::new(self).map_err(|_cstr_err| io::Errno::INVAL)?,
134        ))
135    }
136
137    #[inline]
138    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
139    where
140        Self: Sized,
141        F: FnOnce(&CStr) -> io::Result<T>,
142    {
143        with_c_str(self.as_bytes(), f)
144    }
145}
146
147#[cfg(feature = "alloc")]
148impl Arg for &String {
149    #[inline]
150    fn as_str(&self) -> io::Result<&str> {
151        Ok(self)
152    }
153
154    #[cfg(feature = "alloc")]
155    #[inline]
156    fn to_string_lossy(&self) -> Cow<'_, str> {
157        Cow::Borrowed(self)
158    }
159
160    #[cfg(feature = "alloc")]
161    #[inline]
162    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
163        Ok(Cow::Owned(
164            CString::new(String::as_str(self)).map_err(|_cstr_err| io::Errno::INVAL)?,
165        ))
166    }
167
168    #[cfg(feature = "alloc")]
169    #[inline]
170    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
171    where
172        Self: 'b,
173    {
174        self.as_str().into_c_str()
175    }
176
177    #[inline]
178    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
179    where
180        Self: Sized,
181        F: FnOnce(&CStr) -> io::Result<T>,
182    {
183        with_c_str(self.as_bytes(), f)
184    }
185}
186
187#[cfg(feature = "alloc")]
188impl Arg for String {
189    #[inline]
190    fn as_str(&self) -> io::Result<&str> {
191        Ok(self)
192    }
193
194    #[cfg(feature = "alloc")]
195    #[inline]
196    fn to_string_lossy(&self) -> Cow<'_, str> {
197        Cow::Borrowed(self)
198    }
199
200    #[cfg(feature = "alloc")]
201    #[inline]
202    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
203        Ok(Cow::Owned(
204            CString::new(self.as_str()).map_err(|_cstr_err| io::Errno::INVAL)?,
205        ))
206    }
207
208    #[cfg(feature = "alloc")]
209    #[inline]
210    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
211    where
212        Self: 'b,
213    {
214        Ok(Cow::Owned(
215            CString::new(self).map_err(|_cstr_err| io::Errno::INVAL)?,
216        ))
217    }
218
219    #[inline]
220    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
221    where
222        Self: Sized,
223        F: FnOnce(&CStr) -> io::Result<T>,
224    {
225        f(&CString::new(self).map_err(|_cstr_err| io::Errno::INVAL)?)
226    }
227}
228
229#[cfg(feature = "std")]
230impl Arg for &OsStr {
231    #[inline]
232    fn as_str(&self) -> io::Result<&str> {
233        self.to_str().ok_or(io::Errno::INVAL)
234    }
235
236    #[cfg(feature = "alloc")]
237    #[inline]
238    fn to_string_lossy(&self) -> Cow<'_, str> {
239        OsStr::to_string_lossy(self)
240    }
241
242    #[cfg(feature = "alloc")]
243    #[inline]
244    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
245        Ok(Cow::Owned(
246            CString::new(self.as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
247        ))
248    }
249
250    #[cfg(feature = "alloc")]
251    #[inline]
252    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
253    where
254        Self: 'b,
255    {
256        Ok(Cow::Owned(
257            CString::new(self.as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
258        ))
259    }
260
261    #[inline]
262    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
263    where
264        Self: Sized,
265        F: FnOnce(&CStr) -> io::Result<T>,
266    {
267        with_c_str(self.as_bytes(), f)
268    }
269}
270
271#[cfg(feature = "std")]
272impl Arg for &OsString {
273    #[inline]
274    fn as_str(&self) -> io::Result<&str> {
275        OsString::as_os_str(self).to_str().ok_or(io::Errno::INVAL)
276    }
277
278    #[cfg(feature = "alloc")]
279    #[inline]
280    fn to_string_lossy(&self) -> Cow<'_, str> {
281        self.as_os_str().to_string_lossy()
282    }
283
284    #[cfg(feature = "alloc")]
285    #[inline]
286    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
287        Ok(Cow::Owned(
288            CString::new(OsString::as_os_str(self).as_bytes())
289                .map_err(|_cstr_err| io::Errno::INVAL)?,
290        ))
291    }
292
293    #[cfg(feature = "alloc")]
294    #[inline]
295    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
296    where
297        Self: 'b,
298    {
299        self.as_os_str().into_c_str()
300    }
301
302    #[inline]
303    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
304    where
305        Self: Sized,
306        F: FnOnce(&CStr) -> io::Result<T>,
307    {
308        with_c_str(self.as_bytes(), f)
309    }
310}
311
312#[cfg(feature = "std")]
313impl Arg for OsString {
314    #[inline]
315    fn as_str(&self) -> io::Result<&str> {
316        self.as_os_str().to_str().ok_or(io::Errno::INVAL)
317    }
318
319    #[cfg(feature = "alloc")]
320    #[inline]
321    fn to_string_lossy(&self) -> Cow<'_, str> {
322        self.as_os_str().to_string_lossy()
323    }
324
325    #[cfg(feature = "alloc")]
326    #[inline]
327    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
328        Ok(Cow::Owned(
329            CString::new(self.as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
330        ))
331    }
332
333    #[cfg(feature = "alloc")]
334    #[inline]
335    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
336    where
337        Self: 'b,
338    {
339        Ok(Cow::Owned(
340            CString::new(self.into_vec()).map_err(|_cstr_err| io::Errno::INVAL)?,
341        ))
342    }
343
344    #[inline]
345    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
346    where
347        Self: Sized,
348        F: FnOnce(&CStr) -> io::Result<T>,
349    {
350        f(&CString::new(self.into_vec()).map_err(|_cstr_err| io::Errno::INVAL)?)
351    }
352}
353
354#[cfg(feature = "std")]
355impl Arg for &Path {
356    #[inline]
357    fn as_str(&self) -> io::Result<&str> {
358        self.as_os_str().to_str().ok_or(io::Errno::INVAL)
359    }
360
361    #[cfg(feature = "alloc")]
362    #[inline]
363    fn to_string_lossy(&self) -> Cow<'_, str> {
364        Path::to_string_lossy(self)
365    }
366
367    #[cfg(feature = "alloc")]
368    #[inline]
369    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
370        Ok(Cow::Owned(
371            CString::new(self.as_os_str().as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
372        ))
373    }
374
375    #[cfg(feature = "alloc")]
376    #[inline]
377    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
378    where
379        Self: 'b,
380    {
381        Ok(Cow::Owned(
382            CString::new(self.as_os_str().as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
383        ))
384    }
385
386    #[inline]
387    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
388    where
389        Self: Sized,
390        F: FnOnce(&CStr) -> io::Result<T>,
391    {
392        with_c_str(self.as_os_str().as_bytes(), f)
393    }
394}
395
396#[cfg(feature = "std")]
397impl Arg for &PathBuf {
398    #[inline]
399    fn as_str(&self) -> io::Result<&str> {
400        PathBuf::as_path(self)
401            .as_os_str()
402            .to_str()
403            .ok_or(io::Errno::INVAL)
404    }
405
406    #[cfg(feature = "alloc")]
407    #[inline]
408    fn to_string_lossy(&self) -> Cow<'_, str> {
409        self.as_path().to_string_lossy()
410    }
411
412    #[cfg(feature = "alloc")]
413    #[inline]
414    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
415        Ok(Cow::Owned(
416            CString::new(PathBuf::as_path(self).as_os_str().as_bytes())
417                .map_err(|_cstr_err| io::Errno::INVAL)?,
418        ))
419    }
420
421    #[cfg(feature = "alloc")]
422    #[inline]
423    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
424    where
425        Self: 'b,
426    {
427        self.as_path().into_c_str()
428    }
429
430    #[inline]
431    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
432    where
433        Self: Sized,
434        F: FnOnce(&CStr) -> io::Result<T>,
435    {
436        with_c_str(self.as_os_str().as_bytes(), f)
437    }
438}
439
440#[cfg(feature = "std")]
441impl Arg for PathBuf {
442    #[inline]
443    fn as_str(&self) -> io::Result<&str> {
444        self.as_os_str().to_str().ok_or(io::Errno::INVAL)
445    }
446
447    #[cfg(feature = "alloc")]
448    #[inline]
449    fn to_string_lossy(&self) -> Cow<'_, str> {
450        self.as_os_str().to_string_lossy()
451    }
452
453    #[cfg(feature = "alloc")]
454    #[inline]
455    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
456        Ok(Cow::Owned(
457            CString::new(self.as_os_str().as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
458        ))
459    }
460
461    #[cfg(feature = "alloc")]
462    #[inline]
463    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
464    where
465        Self: 'b,
466    {
467        Ok(Cow::Owned(
468            CString::new(self.into_os_string().into_vec()).map_err(|_cstr_err| io::Errno::INVAL)?,
469        ))
470    }
471
472    #[inline]
473    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
474    where
475        Self: Sized,
476        F: FnOnce(&CStr) -> io::Result<T>,
477    {
478        f(
479            &CString::new(self.into_os_string().into_vec())
480                .map_err(|_cstr_err| io::Errno::INVAL)?,
481        )
482    }
483}
484
485impl Arg for &CStr {
486    #[inline]
487    fn as_str(&self) -> io::Result<&str> {
488        self.to_str().map_err(|_utf8_err| io::Errno::INVAL)
489    }
490
491    #[cfg(feature = "alloc")]
492    #[inline]
493    fn to_string_lossy(&self) -> Cow<'_, str> {
494        CStr::to_string_lossy(self)
495    }
496
497    #[cfg(feature = "alloc")]
498    #[inline]
499    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
500        Ok(Cow::Borrowed(self))
501    }
502
503    #[cfg(feature = "alloc")]
504    #[inline]
505    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
506    where
507        Self: 'b,
508    {
509        Ok(Cow::Borrowed(self))
510    }
511
512    #[inline]
513    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
514    where
515        Self: Sized,
516        F: FnOnce(&CStr) -> io::Result<T>,
517    {
518        f(self)
519    }
520}
521
522#[cfg(feature = "alloc")]
523impl Arg for &CString {
524    #[inline]
525    fn as_str(&self) -> io::Result<&str> {
526        unimplemented!()
527    }
528
529    #[cfg(feature = "alloc")]
530    #[inline]
531    fn to_string_lossy(&self) -> Cow<'_, str> {
532        unimplemented!()
533    }
534
535    #[cfg(feature = "alloc")]
536    #[inline]
537    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
538        Ok(Cow::Borrowed(self))
539    }
540
541    #[cfg(feature = "alloc")]
542    #[inline]
543    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
544    where
545        Self: 'b,
546    {
547        Ok(Cow::Borrowed(self))
548    }
549
550    #[inline]
551    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
552    where
553        Self: Sized,
554        F: FnOnce(&CStr) -> io::Result<T>,
555    {
556        f(self)
557    }
558}
559
560#[cfg(feature = "alloc")]
561impl Arg for CString {
562    #[inline]
563    fn as_str(&self) -> io::Result<&str> {
564        self.to_str().map_err(|_utf8_err| io::Errno::INVAL)
565    }
566
567    #[cfg(feature = "alloc")]
568    #[inline]
569    fn to_string_lossy(&self) -> Cow<'_, str> {
570        CStr::to_string_lossy(self)
571    }
572
573    #[cfg(feature = "alloc")]
574    #[inline]
575    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
576        Ok(Cow::Borrowed(self))
577    }
578
579    #[cfg(feature = "alloc")]
580    #[inline]
581    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
582    where
583        Self: 'b,
584    {
585        Ok(Cow::Owned(self))
586    }
587
588    #[inline]
589    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
590    where
591        Self: Sized,
592        F: FnOnce(&CStr) -> io::Result<T>,
593    {
594        f(&self)
595    }
596}
597
598#[cfg(feature = "alloc")]
599impl<'a> Arg for Cow<'a, str> {
600    #[inline]
601    fn as_str(&self) -> io::Result<&str> {
602        Ok(self)
603    }
604
605    #[cfg(feature = "alloc")]
606    #[inline]
607    fn to_string_lossy(&self) -> Cow<'_, str> {
608        Cow::Borrowed(self)
609    }
610
611    #[cfg(feature = "alloc")]
612    #[inline]
613    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
614        Ok(Cow::Owned(
615            CString::new(self.as_ref()).map_err(|_cstr_err| io::Errno::INVAL)?,
616        ))
617    }
618
619    #[cfg(feature = "alloc")]
620    #[inline]
621    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
622    where
623        Self: 'b,
624    {
625        Ok(Cow::Owned(
626            match self {
627                Cow::Owned(s) => CString::new(s),
628                Cow::Borrowed(s) => CString::new(s),
629            }
630            .map_err(|_cstr_err| io::Errno::INVAL)?,
631        ))
632    }
633
634    #[inline]
635    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
636    where
637        Self: Sized,
638        F: FnOnce(&CStr) -> io::Result<T>,
639    {
640        with_c_str(self.as_bytes(), f)
641    }
642}
643
644#[cfg(feature = "std")]
645#[cfg(feature = "alloc")]
646impl<'a> Arg for Cow<'a, OsStr> {
647    #[inline]
648    fn as_str(&self) -> io::Result<&str> {
649        (**self).to_str().ok_or(io::Errno::INVAL)
650    }
651
652    #[cfg(feature = "alloc")]
653    #[inline]
654    fn to_string_lossy(&self) -> Cow<'_, str> {
655        (**self).to_string_lossy()
656    }
657
658    #[cfg(feature = "alloc")]
659    #[inline]
660    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
661        Ok(Cow::Owned(
662            CString::new(self.as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
663        ))
664    }
665
666    #[cfg(feature = "alloc")]
667    #[inline]
668    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
669    where
670        Self: 'b,
671    {
672        Ok(Cow::Owned(
673            match self {
674                Cow::Owned(os) => CString::new(os.into_vec()),
675                Cow::Borrowed(os) => CString::new(os.as_bytes()),
676            }
677            .map_err(|_cstr_err| io::Errno::INVAL)?,
678        ))
679    }
680
681    #[inline]
682    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
683    where
684        Self: Sized,
685        F: FnOnce(&CStr) -> io::Result<T>,
686    {
687        with_c_str(self.as_bytes(), f)
688    }
689}
690
691#[cfg(feature = "alloc")]
692impl<'a> Arg for Cow<'a, CStr> {
693    #[inline]
694    fn as_str(&self) -> io::Result<&str> {
695        self.to_str().map_err(|_utf8_err| io::Errno::INVAL)
696    }
697
698    #[cfg(feature = "alloc")]
699    #[inline]
700    fn to_string_lossy(&self) -> Cow<'_, str> {
701        let borrow: &CStr = core::borrow::Borrow::borrow(self);
702        borrow.to_string_lossy()
703    }
704
705    #[cfg(feature = "alloc")]
706    #[inline]
707    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
708        Ok(Cow::Borrowed(self))
709    }
710
711    #[cfg(feature = "alloc")]
712    #[inline]
713    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
714    where
715        Self: 'b,
716    {
717        Ok(self)
718    }
719
720    #[inline]
721    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
722    where
723        Self: Sized,
724        F: FnOnce(&CStr) -> io::Result<T>,
725    {
726        f(&self)
727    }
728}
729
730#[cfg(feature = "std")]
731impl<'a> Arg for Component<'a> {
732    #[inline]
733    fn as_str(&self) -> io::Result<&str> {
734        self.as_os_str().to_str().ok_or(io::Errno::INVAL)
735    }
736
737    #[cfg(feature = "alloc")]
738    #[inline]
739    fn to_string_lossy(&self) -> Cow<'_, str> {
740        self.as_os_str().to_string_lossy()
741    }
742
743    #[cfg(feature = "alloc")]
744    #[inline]
745    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
746        Ok(Cow::Owned(
747            CString::new(self.as_os_str().as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
748        ))
749    }
750
751    #[cfg(feature = "alloc")]
752    #[inline]
753    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
754    where
755        Self: 'b,
756    {
757        Ok(Cow::Owned(
758            CString::new(self.as_os_str().as_bytes()).map_err(|_cstr_err| io::Errno::INVAL)?,
759        ))
760    }
761
762    #[inline]
763    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
764    where
765        Self: Sized,
766        F: FnOnce(&CStr) -> io::Result<T>,
767    {
768        with_c_str(self.as_os_str().as_bytes(), f)
769    }
770}
771
772#[cfg(feature = "std")]
773impl<'a> Arg for Components<'a> {
774    #[inline]
775    fn as_str(&self) -> io::Result<&str> {
776        self.as_path().to_str().ok_or(io::Errno::INVAL)
777    }
778
779    #[cfg(feature = "alloc")]
780    #[inline]
781    fn to_string_lossy(&self) -> Cow<'_, str> {
782        self.as_path().to_string_lossy()
783    }
784
785    #[cfg(feature = "alloc")]
786    #[inline]
787    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
788        Ok(Cow::Owned(
789            CString::new(self.as_path().as_os_str().as_bytes())
790                .map_err(|_cstr_err| io::Errno::INVAL)?,
791        ))
792    }
793
794    #[cfg(feature = "alloc")]
795    #[inline]
796    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
797    where
798        Self: 'b,
799    {
800        Ok(Cow::Owned(
801            CString::new(self.as_path().as_os_str().as_bytes())
802                .map_err(|_cstr_err| io::Errno::INVAL)?,
803        ))
804    }
805
806    #[inline]
807    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
808    where
809        Self: Sized,
810        F: FnOnce(&CStr) -> io::Result<T>,
811    {
812        with_c_str(self.as_path().as_os_str().as_bytes(), f)
813    }
814}
815
816#[cfg(feature = "std")]
817impl<'a> Arg for Iter<'a> {
818    #[inline]
819    fn as_str(&self) -> io::Result<&str> {
820        self.as_path().to_str().ok_or(io::Errno::INVAL)
821    }
822
823    #[cfg(feature = "alloc")]
824    #[inline]
825    fn to_string_lossy(&self) -> Cow<'_, str> {
826        self.as_path().to_string_lossy()
827    }
828
829    #[cfg(feature = "alloc")]
830    #[inline]
831    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
832        Ok(Cow::Owned(
833            CString::new(self.as_path().as_os_str().as_bytes())
834                .map_err(|_cstr_err| io::Errno::INVAL)?,
835        ))
836    }
837
838    #[cfg(feature = "alloc")]
839    #[inline]
840    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
841    where
842        Self: 'b,
843    {
844        Ok(Cow::Owned(
845            CString::new(self.as_path().as_os_str().as_bytes())
846                .map_err(|_cstr_err| io::Errno::INVAL)?,
847        ))
848    }
849
850    #[inline]
851    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
852    where
853        Self: Sized,
854        F: FnOnce(&CStr) -> io::Result<T>,
855    {
856        with_c_str(self.as_path().as_os_str().as_bytes(), f)
857    }
858}
859
860impl Arg for &[u8] {
861    #[inline]
862    fn as_str(&self) -> io::Result<&str> {
863        str::from_utf8(self).map_err(|_utf8_err| io::Errno::INVAL)
864    }
865
866    #[cfg(feature = "alloc")]
867    #[inline]
868    fn to_string_lossy(&self) -> Cow<'_, str> {
869        String::from_utf8_lossy(self)
870    }
871
872    #[cfg(feature = "alloc")]
873    #[inline]
874    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
875        Ok(Cow::Owned(
876            CString::new(*self).map_err(|_cstr_err| io::Errno::INVAL)?,
877        ))
878    }
879
880    #[cfg(feature = "alloc")]
881    #[inline]
882    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
883    where
884        Self: 'b,
885    {
886        Ok(Cow::Owned(
887            CString::new(self).map_err(|_cstr_err| io::Errno::INVAL)?,
888        ))
889    }
890
891    #[inline]
892    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
893    where
894        Self: Sized,
895        F: FnOnce(&CStr) -> io::Result<T>,
896    {
897        with_c_str(self, f)
898    }
899}
900
901#[cfg(feature = "alloc")]
902impl Arg for &Vec<u8> {
903    #[inline]
904    fn as_str(&self) -> io::Result<&str> {
905        str::from_utf8(self).map_err(|_utf8_err| io::Errno::INVAL)
906    }
907
908    #[cfg(feature = "alloc")]
909    #[inline]
910    fn to_string_lossy(&self) -> Cow<'_, str> {
911        String::from_utf8_lossy(self)
912    }
913
914    #[cfg(feature = "alloc")]
915    #[inline]
916    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
917        Ok(Cow::Owned(
918            CString::new(self.as_slice()).map_err(|_cstr_err| io::Errno::INVAL)?,
919        ))
920    }
921
922    #[cfg(feature = "alloc")]
923    #[inline]
924    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
925    where
926        Self: 'b,
927    {
928        Ok(Cow::Owned(
929            CString::new(self.as_slice()).map_err(|_cstr_err| io::Errno::INVAL)?,
930        ))
931    }
932
933    #[inline]
934    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
935    where
936        Self: Sized,
937        F: FnOnce(&CStr) -> io::Result<T>,
938    {
939        with_c_str(self, f)
940    }
941}
942
943#[cfg(feature = "alloc")]
944impl Arg for Vec<u8> {
945    #[inline]
946    fn as_str(&self) -> io::Result<&str> {
947        str::from_utf8(self).map_err(|_utf8_err| io::Errno::INVAL)
948    }
949
950    #[cfg(feature = "alloc")]
951    #[inline]
952    fn to_string_lossy(&self) -> Cow<'_, str> {
953        String::from_utf8_lossy(self)
954    }
955
956    #[cfg(feature = "alloc")]
957    #[inline]
958    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
959        Ok(Cow::Owned(
960            CString::new(self.as_slice()).map_err(|_cstr_err| io::Errno::INVAL)?,
961        ))
962    }
963
964    #[cfg(feature = "alloc")]
965    #[inline]
966    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
967    where
968        Self: 'b,
969    {
970        Ok(Cow::Owned(
971            CString::new(self).map_err(|_cstr_err| io::Errno::INVAL)?,
972        ))
973    }
974
975    #[inline]
976    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
977    where
978        Self: Sized,
979        F: FnOnce(&CStr) -> io::Result<T>,
980    {
981        f(&CString::new(self).map_err(|_cstr_err| io::Errno::INVAL)?)
982    }
983}
984
985#[cfg(feature = "itoa")]
986impl Arg for DecInt {
987    #[inline]
988    fn as_str(&self) -> io::Result<&str> {
989        Ok(self.as_str())
990    }
991
992    #[cfg(feature = "alloc")]
993    #[inline]
994    fn to_string_lossy(&self) -> Cow<'_, str> {
995        Cow::Borrowed(self.as_str())
996    }
997
998    #[cfg(feature = "alloc")]
999    #[inline]
1000    fn as_cow_c_str(&self) -> io::Result<Cow<'_, CStr>> {
1001        Ok(Cow::Borrowed(self.as_c_str()))
1002    }
1003
1004    #[cfg(feature = "alloc")]
1005    #[inline]
1006    fn into_c_str<'b>(self) -> io::Result<Cow<'b, CStr>>
1007    where
1008        Self: 'b,
1009    {
1010        Ok(Cow::Owned(self.as_c_str().to_owned()))
1011    }
1012
1013    #[inline]
1014    fn into_with_c_str<T, F>(self, f: F) -> io::Result<T>
1015    where
1016        Self: Sized,
1017        F: FnOnce(&CStr) -> io::Result<T>,
1018    {
1019        f(self.as_c_str())
1020    }
1021}
1022
1023/// Runs a closure with `bytes` passed in as a `&CStr`.
1024#[allow(unsafe_code, clippy::int_plus_one)]
1025#[inline]
1026fn with_c_str<T, F>(bytes: &[u8], f: F) -> io::Result<T>
1027where
1028    F: FnOnce(&CStr) -> io::Result<T>,
1029{
1030    // Most paths are less than `SMALL_PATH_BUFFER_SIZE` long. The rest can go
1031    // through the dynamic allocation path. If you're opening many files in a
1032    // directory with a long path, consider opening the directory and using
1033    // `openat` to open the files under it, which will avoid this, and is often
1034    // faster in the OS as well.
1035
1036    // Test with `>=` so that we have room for the trailing NUL.
1037    if bytes.len() >= SMALL_PATH_BUFFER_SIZE {
1038        return with_c_str_slow_path(bytes, f);
1039    }
1040
1041    // Taken from
1042    // <https://github.com/rust-lang/rust/blob/a00f8ba7fcac1b27341679c51bf5a3271fa82df3/library/std/src/sys/common/small_c_string.rs>
1043    let mut buf = MaybeUninit::<[u8; SMALL_PATH_BUFFER_SIZE]>::uninit();
1044    let buf_ptr = buf.as_mut_ptr().cast::<u8>();
1045
1046    // This helps test our safety condition below.
1047    debug_assert!(bytes.len() + 1 <= SMALL_PATH_BUFFER_SIZE);
1048
1049    // SAFETY: `bytes.len() < SMALL_PATH_BUFFER_SIZE` which means we have space
1050    // for `bytes.len() + 1` u8s:
1051    unsafe {
1052        ptr::copy_nonoverlapping(bytes.as_ptr(), buf_ptr, bytes.len());
1053        buf_ptr.add(bytes.len()).write(0);
1054    }
1055
1056    // SAFETY: We just wrote the bytes above and they will remain valid for the
1057    // duration of `f` b/c buf doesn't get dropped until the end of the
1058    // function.
1059    match CStr::from_bytes_with_nul(unsafe { slice::from_raw_parts(buf_ptr, bytes.len() + 1) }) {
1060        Ok(s) => f(s),
1061        Err(_) => Err(io::Errno::INVAL),
1062    }
1063}
1064
1065/// The slow path which handles any length. In theory OS's only support up to
1066/// `PATH_MAX`, but we let the OS enforce that.
1067#[allow(unsafe_code, clippy::int_plus_one)]
1068#[cold]
1069fn with_c_str_slow_path<T, F>(bytes: &[u8], f: F) -> io::Result<T>
1070where
1071    F: FnOnce(&CStr) -> io::Result<T>,
1072{
1073    #[cfg(feature = "alloc")]
1074    {
1075        f(&CString::new(bytes).map_err(|_cstr_err| io::Errno::INVAL)?)
1076    }
1077
1078    #[cfg(not(feature = "alloc"))]
1079    {
1080        #[cfg(all(libc, not(any(target_os = "hurd", target_os = "wasi"))))]
1081        const LARGE_PATH_BUFFER_SIZE: usize = libc::PATH_MAX as usize;
1082        #[cfg(linux_raw)]
1083        const LARGE_PATH_BUFFER_SIZE: usize = linux_raw_sys::general::PATH_MAX as usize;
1084        #[cfg(any(target_os = "hurd", target_os = "wasi"))]
1085        const LARGE_PATH_BUFFER_SIZE: usize = 4096 as usize; // TODO: upstream this
1086
1087        // Taken from
1088        // <https://github.com/rust-lang/rust/blob/a00f8ba7fcac1b27341679c51bf5a3271fa82df3/library/std/src/sys/common/small_c_string.rs>
1089        let mut buf = MaybeUninit::<[u8; LARGE_PATH_BUFFER_SIZE]>::uninit();
1090        let buf_ptr = buf.as_mut_ptr().cast::<u8>();
1091
1092        // This helps test our safety condition below.
1093        if bytes.len() + 1 > LARGE_PATH_BUFFER_SIZE {
1094            return Err(io::Errno::NAMETOOLONG);
1095        }
1096
1097        // SAFETY: `bytes.len() < LARGE_PATH_BUFFER_SIZE` which means we have
1098        // space for `bytes.len() + 1` u8s:
1099        unsafe {
1100            ptr::copy_nonoverlapping(bytes.as_ptr(), buf_ptr, bytes.len());
1101            buf_ptr.add(bytes.len()).write(0);
1102        }
1103
1104        // SAFETY: We just wrote the bytes above and they will remain valid for
1105        // the duration of `f` b/c buf doesn't get dropped until the end of the
1106        // function.
1107        match CStr::from_bytes_with_nul(unsafe { slice::from_raw_parts(buf_ptr, bytes.len() + 1) })
1108        {
1109            Ok(s) => f(s),
1110            Err(_) => Err(io::Errno::INVAL),
1111        }
1112    }
1113}
rustix/path/arg.rs

rustix/path/
arg.rs
