]> git.proxmox.com Git - rustc.git/blob - src/libstd/env.rs
Imported Upstream version 1.9.0+dfsg1
[rustc.git] / src / libstd / env.rs
1 // Copyright 2012-2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! Inspection and manipulation of the process's environment.
12 //!
13 //! This module contains methods to inspect various aspects such as
14 //! environment variables, process arguments, the current directory, and various
15 //! other important directories.
16
17 #![stable(feature = "env", since = "1.0.0")]
18
19 use prelude::v1::*;
20
21 use error::Error;
22 use ffi::{OsStr, OsString};
23 use fmt;
24 use io;
25 use path::{Path, PathBuf};
26 use sys::os as os_imp;
27
28 /// Returns the current working directory as a `PathBuf`.
29 ///
30 /// # Errors
31 ///
32 /// Returns an `Err` if the current working directory value is invalid.
33 /// Possible cases:
34 ///
35 /// * Current directory does not exist.
36 /// * There are insufficient permissions to access the current directory.
37 ///
38 /// # Examples
39 ///
40 /// ```
41 /// use std::env;
42 ///
43 /// // We assume that we are in a valid directory.
44 /// let p = env::current_dir().unwrap();
45 /// println!("The current directory is {}", p.display());
46 /// ```
47 #[stable(feature = "env", since = "1.0.0")]
48 pub fn current_dir() -> io::Result<PathBuf> {
49 os_imp::getcwd()
50 }
51
52 /// Changes the current working directory to the specified path, returning
53 /// whether the change was completed successfully or not.
54 ///
55 /// # Examples
56 ///
57 /// ```
58 /// use std::env;
59 /// use std::path::Path;
60 ///
61 /// let root = Path::new("/");
62 /// assert!(env::set_current_dir(&root).is_ok());
63 /// println!("Successfully changed working directory to {}!", root.display());
64 /// ```
65 #[stable(feature = "env", since = "1.0.0")]
66 pub fn set_current_dir<P: AsRef<Path>>(p: P) -> io::Result<()> {
67 os_imp::chdir(p.as_ref())
68 }
69
70 /// An iterator over a snapshot of the environment variables of this process.
71 ///
72 /// This iterator is created through `std::env::vars()` and yields `(String,
73 /// String)` pairs.
74 #[stable(feature = "env", since = "1.0.0")]
75 pub struct Vars { inner: VarsOs }
76
77 /// An iterator over a snapshot of the environment variables of this process.
78 ///
79 /// This iterator is created through `std::env::vars_os()` and yields
80 /// `(OsString, OsString)` pairs.
81 #[stable(feature = "env", since = "1.0.0")]
82 pub struct VarsOs { inner: os_imp::Env }
83
84 /// Returns an iterator of (variable, value) pairs of strings, for all the
85 /// environment variables of the current process.
86 ///
87 /// The returned iterator contains a snapshot of the process's environment
88 /// variables at the time of this invocation, modifications to environment
89 /// variables afterwards will not be reflected in the returned iterator.
90 ///
91 /// # Panics
92 ///
93 /// While iterating, the returned iterator will panic if any key or value in the
94 /// environment is not valid unicode. If this is not desired, consider using the
95 /// `env::vars_os` function.
96 ///
97 /// # Examples
98 ///
99 /// ```
100 /// use std::env;
101 ///
102 /// // We will iterate through the references to the element returned by
103 /// // env::vars();
104 /// for (key, value) in env::vars() {
105 /// println!("{}: {}", key, value);
106 /// }
107 /// ```
108 #[stable(feature = "env", since = "1.0.0")]
109 pub fn vars() -> Vars {
110 Vars { inner: vars_os() }
111 }
112
113 /// Returns an iterator of (variable, value) pairs of OS strings, for all the
114 /// environment variables of the current process.
115 ///
116 /// The returned iterator contains a snapshot of the process's environment
117 /// variables at the time of this invocation, modifications to environment
118 /// variables afterwards will not be reflected in the returned iterator.
119 ///
120 /// # Examples
121 ///
122 /// ```
123 /// use std::env;
124 ///
125 /// // We will iterate through the references to the element returned by
126 /// // env::vars_os();
127 /// for (key, value) in env::vars_os() {
128 /// println!("{:?}: {:?}", key, value);
129 /// }
130 /// ```
131 #[stable(feature = "env", since = "1.0.0")]
132 pub fn vars_os() -> VarsOs {
133 VarsOs { inner: os_imp::env() }
134 }
135
136 #[stable(feature = "env", since = "1.0.0")]
137 impl Iterator for Vars {
138 type Item = (String, String);
139 fn next(&mut self) -> Option<(String, String)> {
140 self.inner.next().map(|(a, b)| {
141 (a.into_string().unwrap(), b.into_string().unwrap())
142 })
143 }
144 fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
145 }
146
147 #[stable(feature = "env", since = "1.0.0")]
148 impl Iterator for VarsOs {
149 type Item = (OsString, OsString);
150 fn next(&mut self) -> Option<(OsString, OsString)> { self.inner.next() }
151 fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
152 }
153
154 /// Fetches the environment variable `key` from the current process.
155 ///
156 /// The returned result is `Ok(s)` if the environment variable is present and is
157 /// valid unicode. If the environment variable is not present, or it is not
158 /// valid unicode, then `Err` will be returned.
159 ///
160 /// # Examples
161 ///
162 /// ```
163 /// use std::env;
164 ///
165 /// let key = "HOME";
166 /// match env::var(key) {
167 /// Ok(val) => println!("{}: {:?}", key, val),
168 /// Err(e) => println!("couldn't interpret {}: {}", key, e),
169 /// }
170 /// ```
171 #[stable(feature = "env", since = "1.0.0")]
172 pub fn var<K: AsRef<OsStr>>(key: K) -> Result<String, VarError> {
173 _var(key.as_ref())
174 }
175
176 fn _var(key: &OsStr) -> Result<String, VarError> {
177 match var_os(key) {
178 Some(s) => s.into_string().map_err(VarError::NotUnicode),
179 None => Err(VarError::NotPresent)
180 }
181 }
182
183 /// Fetches the environment variable `key` from the current process, returning
184 /// `None` if the variable isn't set.
185 ///
186 /// # Examples
187 ///
188 /// ```
189 /// use std::env;
190 ///
191 /// let key = "HOME";
192 /// match env::var_os(key) {
193 /// Some(val) => println!("{}: {:?}", key, val),
194 /// None => println!("{} is not defined in the environment.", key)
195 /// }
196 /// ```
197 #[stable(feature = "env", since = "1.0.0")]
198 pub fn var_os<K: AsRef<OsStr>>(key: K) -> Option<OsString> {
199 _var_os(key.as_ref())
200 }
201
202 fn _var_os(key: &OsStr) -> Option<OsString> {
203 os_imp::getenv(key).unwrap_or_else(|e| {
204 panic!("failed to get environment variable `{:?}`: {}", key, e)
205 })
206 }
207
208 /// Possible errors from the `env::var` method.
209 #[derive(Debug, PartialEq, Eq, Clone)]
210 #[stable(feature = "env", since = "1.0.0")]
211 pub enum VarError {
212 /// The specified environment variable was not present in the current
213 /// process's environment.
214 #[stable(feature = "env", since = "1.0.0")]
215 NotPresent,
216
217 /// The specified environment variable was found, but it did not contain
218 /// valid unicode data. The found data is returned as a payload of this
219 /// variant.
220 #[stable(feature = "env", since = "1.0.0")]
221 NotUnicode(#[stable(feature = "env", since = "1.0.0")] OsString),
222 }
223
224 #[stable(feature = "env", since = "1.0.0")]
225 impl fmt::Display for VarError {
226 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
227 match *self {
228 VarError::NotPresent => write!(f, "environment variable not found"),
229 VarError::NotUnicode(ref s) => {
230 write!(f, "environment variable was not valid unicode: {:?}", s)
231 }
232 }
233 }
234 }
235
236 #[stable(feature = "env", since = "1.0.0")]
237 impl Error for VarError {
238 fn description(&self) -> &str {
239 match *self {
240 VarError::NotPresent => "environment variable not found",
241 VarError::NotUnicode(..) => "environment variable was not valid unicode",
242 }
243 }
244 }
245
246 /// Sets the environment variable `k` to the value `v` for the currently running
247 /// process.
248 ///
249 /// Note that while concurrent access to environment variables is safe in Rust,
250 /// some platforms only expose inherently unsafe non-threadsafe APIs for
251 /// inspecting the environment. As a result extra care needs to be taken when
252 /// auditing calls to unsafe external FFI functions to ensure that any external
253 /// environment accesses are properly synchronized with accesses in Rust.
254 ///
255 /// Discussion of this unsafety on Unix may be found in:
256 ///
257 /// - [Austin Group Bugzilla](http://austingroupbugs.net/view.php?id=188)
258 /// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2)
259 ///
260 /// # Panics
261 ///
262 /// This function may panic if `key` is empty, contains an ASCII equals sign
263 /// `'='` or the NUL character `'\0'`, or when the value contains the NUL
264 /// character.
265 ///
266 /// # Examples
267 ///
268 /// ```
269 /// use std::env;
270 ///
271 /// let key = "KEY";
272 /// env::set_var(key, "VALUE");
273 /// assert_eq!(env::var(key), Ok("VALUE".to_string()));
274 /// ```
275 #[stable(feature = "env", since = "1.0.0")]
276 pub fn set_var<K: AsRef<OsStr>, V: AsRef<OsStr>>(k: K, v: V) {
277 _set_var(k.as_ref(), v.as_ref())
278 }
279
280 fn _set_var(k: &OsStr, v: &OsStr) {
281 os_imp::setenv(k, v).unwrap_or_else(|e| {
282 panic!("failed to set environment variable `{:?}` to `{:?}`: {}",
283 k, v, e)
284 })
285 }
286
287 /// Removes an environment variable from the environment of the currently running process.
288 ///
289 /// Note that while concurrent access to environment variables is safe in Rust,
290 /// some platforms only expose inherently unsafe non-threadsafe APIs for
291 /// inspecting the environment. As a result extra care needs to be taken when
292 /// auditing calls to unsafe external FFI functions to ensure that any external
293 /// environment accesses are properly synchronized with accesses in Rust.
294 ///
295 /// Discussion of this unsafety on Unix may be found in:
296 ///
297 /// - [Austin Group Bugzilla](http://austingroupbugs.net/view.php?id=188)
298 /// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2)
299 ///
300 /// # Panics
301 ///
302 /// This function may panic if `key` is empty, contains an ASCII equals sign
303 /// `'='` or the NUL character `'\0'`, or when the value contains the NUL
304 /// character.
305 ///
306 /// # Examples
307 ///
308 /// ```
309 /// use std::env;
310 ///
311 /// let key = "KEY";
312 /// env::set_var(key, "VALUE");
313 /// assert_eq!(env::var(key), Ok("VALUE".to_string()));
314 ///
315 /// env::remove_var(key);
316 /// assert!(env::var(key).is_err());
317 /// ```
318 #[stable(feature = "env", since = "1.0.0")]
319 pub fn remove_var<K: AsRef<OsStr>>(k: K) {
320 _remove_var(k.as_ref())
321 }
322
323 fn _remove_var(k: &OsStr) {
324 os_imp::unsetenv(k).unwrap_or_else(|e| {
325 panic!("failed to remove environment variable `{:?}`: {}", k, e)
326 })
327 }
328
329 /// An iterator over `PathBuf` instances for parsing an environment variable
330 /// according to platform-specific conventions.
331 ///
332 /// This structure is returned from `std::env::split_paths`.
333 #[stable(feature = "env", since = "1.0.0")]
334 pub struct SplitPaths<'a> { inner: os_imp::SplitPaths<'a> }
335
336 /// Parses input according to platform conventions for the `PATH`
337 /// environment variable.
338 ///
339 /// Returns an iterator over the paths contained in `unparsed`.
340 ///
341 /// # Examples
342 ///
343 /// ```
344 /// use std::env;
345 ///
346 /// let key = "PATH";
347 /// match env::var_os(key) {
348 /// Some(paths) => {
349 /// for path in env::split_paths(&paths) {
350 /// println!("'{}'", path.display());
351 /// }
352 /// }
353 /// None => println!("{} is not defined in the environment.", key)
354 /// }
355 /// ```
356 #[stable(feature = "env", since = "1.0.0")]
357 pub fn split_paths<T: AsRef<OsStr> + ?Sized>(unparsed: &T) -> SplitPaths {
358 SplitPaths { inner: os_imp::split_paths(unparsed.as_ref()) }
359 }
360
361 #[stable(feature = "env", since = "1.0.0")]
362 impl<'a> Iterator for SplitPaths<'a> {
363 type Item = PathBuf;
364 fn next(&mut self) -> Option<PathBuf> { self.inner.next() }
365 fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
366 }
367
368 /// Error type returned from `std::env::join_paths` when paths fail to be
369 /// joined.
370 #[derive(Debug)]
371 #[stable(feature = "env", since = "1.0.0")]
372 pub struct JoinPathsError {
373 inner: os_imp::JoinPathsError
374 }
375
376 /// Joins a collection of `Path`s appropriately for the `PATH`
377 /// environment variable.
378 ///
379 /// Returns an `OsString` on success.
380 ///
381 /// Returns an `Err` (containing an error message) if one of the input
382 /// `Path`s contains an invalid character for constructing the `PATH`
383 /// variable (a double quote on Windows or a colon on Unix).
384 ///
385 /// # Examples
386 ///
387 /// ```
388 /// use std::env;
389 /// use std::path::PathBuf;
390 ///
391 /// if let Some(path) = env::var_os("PATH") {
392 /// let mut paths = env::split_paths(&path).collect::<Vec<_>>();
393 /// paths.push(PathBuf::from("/home/xyz/bin"));
394 /// let new_path = env::join_paths(paths).unwrap();
395 /// env::set_var("PATH", &new_path);
396 /// }
397 /// ```
398 #[stable(feature = "env", since = "1.0.0")]
399 pub fn join_paths<I, T>(paths: I) -> Result<OsString, JoinPathsError>
400 where I: IntoIterator<Item=T>, T: AsRef<OsStr>
401 {
402 os_imp::join_paths(paths.into_iter()).map_err(|e| {
403 JoinPathsError { inner: e }
404 })
405 }
406
407 #[stable(feature = "env", since = "1.0.0")]
408 impl fmt::Display for JoinPathsError {
409 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
410 self.inner.fmt(f)
411 }
412 }
413
414 #[stable(feature = "env", since = "1.0.0")]
415 impl Error for JoinPathsError {
416 fn description(&self) -> &str { self.inner.description() }
417 }
418
419 /// Returns the path of the current user's home directory if known.
420 ///
421 /// # Unix
422 ///
423 /// Returns the value of the 'HOME' environment variable if it is set
424 /// and not equal to the empty string. Otherwise, it tries to determine the
425 /// home directory by invoking the `getpwuid_r` function on the UID of the
426 /// current user.
427 ///
428 /// # Windows
429 ///
430 /// Returns the value of the 'HOME' environment variable if it is
431 /// set and not equal to the empty string. Otherwise, returns the value of the
432 /// 'USERPROFILE' environment variable if it is set and not equal to the empty
433 /// string. If both do not exist, [`GetUserProfileDirectory`][msdn] is used to
434 /// return the appropriate path.
435 ///
436 /// [msdn]: https://msdn.microsoft.com/en-us/library/windows/desktop/bb762280(v=vs.85).aspx
437 ///
438 /// # Examples
439 ///
440 /// ```
441 /// use std::env;
442 ///
443 /// match env::home_dir() {
444 /// Some(path) => println!("{}", path.display()),
445 /// None => println!("Impossible to get your home dir!"),
446 /// }
447 /// ```
448 #[stable(feature = "env", since = "1.0.0")]
449 pub fn home_dir() -> Option<PathBuf> {
450 os_imp::home_dir()
451 }
452
453 /// Returns the path of a temporary directory.
454 ///
455 /// On Unix, returns the value of the 'TMPDIR' environment variable if it is
456 /// set, otherwise for non-Android it returns '/tmp'. If Android, since there
457 /// is no global temporary folder (it is usually allocated per-app), we return
458 /// '/data/local/tmp'.
459 ///
460 /// On Windows, returns the value of, in order, the 'TMP', 'TEMP',
461 /// 'USERPROFILE' environment variable if any are set and not the empty
462 /// string. Otherwise, tmpdir returns the path of the Windows directory. This
463 /// behavior is identical to that of [GetTempPath][msdn], which this function
464 /// uses internally.
465 ///
466 /// [msdn]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364992(v=vs.85).aspx
467 ///
468 /// ```
469 /// use std::env;
470 /// use std::fs::File;
471 ///
472 /// # fn foo() -> std::io::Result<()> {
473 /// let mut dir = env::temp_dir();
474 /// dir.push("foo.txt");
475 ///
476 /// let f = try!(File::create(dir));
477 /// # Ok(())
478 /// # }
479 /// ```
480 #[stable(feature = "env", since = "1.0.0")]
481 pub fn temp_dir() -> PathBuf {
482 os_imp::temp_dir()
483 }
484
485 /// Returns the full filesystem path of the current running executable.
486 ///
487 /// The path returned is not necessarily a "real path" of the executable as
488 /// there may be intermediate symlinks.
489 ///
490 /// # Errors
491 ///
492 /// Acquiring the path of the current executable is a platform-specific operation
493 /// that can fail for a good number of reasons. Some errors can include, but not
494 /// be limited to, filesystem operations failing or general syscall failures.
495 ///
496 /// # Examples
497 ///
498 /// ```
499 /// use std::env;
500 ///
501 /// match env::current_exe() {
502 /// Ok(exe_path) => println!("Path of this executable is: {}",
503 /// exe_path.display()),
504 /// Err(e) => println!("failed to get current exe path: {}", e),
505 /// };
506 /// ```
507 #[stable(feature = "env", since = "1.0.0")]
508 pub fn current_exe() -> io::Result<PathBuf> {
509 os_imp::current_exe()
510 }
511
512 /// An iterator over the arguments of a process, yielding a `String` value
513 /// for each argument.
514 ///
515 /// This structure is created through the `std::env::args` method.
516 #[stable(feature = "env", since = "1.0.0")]
517 pub struct Args { inner: ArgsOs }
518
519 /// An iterator over the arguments of a process, yielding an `OsString` value
520 /// for each argument.
521 ///
522 /// This structure is created through the `std::env::args_os` method.
523 #[stable(feature = "env", since = "1.0.0")]
524 pub struct ArgsOs { inner: os_imp::Args }
525
526 /// Returns the arguments which this program was started with (normally passed
527 /// via the command line).
528 ///
529 /// The first element is traditionally the path of the executable, but it can be
530 /// set to arbitrary text, and may not even exist. This means this property should
531 /// not be relied upon for security purposes.
532 ///
533 /// # Panics
534 ///
535 /// The returned iterator will panic during iteration if any argument to the
536 /// process is not valid unicode. If this is not desired,
537 /// use the `args_os` function instead.
538 ///
539 /// # Examples
540 ///
541 /// ```
542 /// use std::env;
543 ///
544 /// // Prints each argument on a separate line
545 /// for argument in env::args() {
546 /// println!("{}", argument);
547 /// }
548 /// ```
549 #[stable(feature = "env", since = "1.0.0")]
550 pub fn args() -> Args {
551 Args { inner: args_os() }
552 }
553
554 /// Returns the arguments which this program was started with (normally passed
555 /// via the command line).
556 ///
557 /// The first element is traditionally the path of the executable, but it can be
558 /// set to arbitrary text, and it may not even exist, so this property should
559 /// not be relied upon for security purposes.
560 ///
561 /// # Examples
562 ///
563 /// ```
564 /// use std::env;
565 ///
566 /// // Prints each argument on a separate line
567 /// for argument in env::args_os() {
568 /// println!("{:?}", argument);
569 /// }
570 /// ```
571 #[stable(feature = "env", since = "1.0.0")]
572 pub fn args_os() -> ArgsOs {
573 ArgsOs { inner: os_imp::args() }
574 }
575
576 #[stable(feature = "env", since = "1.0.0")]
577 impl Iterator for Args {
578 type Item = String;
579 fn next(&mut self) -> Option<String> {
580 self.inner.next().map(|s| s.into_string().unwrap())
581 }
582 fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
583 }
584
585 #[stable(feature = "env", since = "1.0.0")]
586 impl ExactSizeIterator for Args {
587 fn len(&self) -> usize { self.inner.len() }
588 }
589
590 #[stable(feature = "env", since = "1.0.0")]
591 impl Iterator for ArgsOs {
592 type Item = OsString;
593 fn next(&mut self) -> Option<OsString> { self.inner.next() }
594 fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
595 }
596
597 #[stable(feature = "env", since = "1.0.0")]
598 impl ExactSizeIterator for ArgsOs {
599 fn len(&self) -> usize { self.inner.len() }
600 }
601
602 /// Constants associated with the current target
603 #[stable(feature = "env", since = "1.0.0")]
604 pub mod consts {
605 /// A string describing the architecture of the CPU that is currently
606 /// in use.
607 ///
608 /// Some possible values:
609 ///
610 /// - x86
611 /// - x86_64
612 /// - arm
613 /// - aarch64
614 /// - mips
615 /// - powerpc
616 /// - powerpc64
617 #[stable(feature = "env", since = "1.0.0")]
618 pub const ARCH: &'static str = super::arch::ARCH;
619
620 /// The family of the operating system. Example value is `unix`.
621 ///
622 /// Some possible values:
623 ///
624 /// - unix
625 /// - windows
626 #[stable(feature = "env", since = "1.0.0")]
627 pub const FAMILY: &'static str = super::os::FAMILY;
628
629 /// A string describing the specific operating system in use.
630 /// Example value is `linux`.
631 ///
632 /// Some possible values:
633 ///
634 /// - linux
635 /// - macos
636 /// - ios
637 /// - freebsd
638 /// - dragonfly
639 /// - bitrig
640 /// - netbsd
641 /// - openbsd
642 /// - solaris
643 /// - android
644 /// - windows
645 #[stable(feature = "env", since = "1.0.0")]
646 pub const OS: &'static str = super::os::OS;
647
648 /// Specifies the filename prefix used for shared libraries on this
649 /// platform. Example value is `lib`.
650 ///
651 /// Some possible values:
652 ///
653 /// - lib
654 /// - `""` (an empty string)
655 #[stable(feature = "env", since = "1.0.0")]
656 pub const DLL_PREFIX: &'static str = super::os::DLL_PREFIX;
657
658 /// Specifies the filename suffix used for shared libraries on this
659 /// platform. Example value is `.so`.
660 ///
661 /// Some possible values:
662 ///
663 /// - .so
664 /// - .dylib
665 /// - .dll
666 #[stable(feature = "env", since = "1.0.0")]
667 pub const DLL_SUFFIX: &'static str = super::os::DLL_SUFFIX;
668
669 /// Specifies the file extension used for shared libraries on this
670 /// platform that goes after the dot. Example value is `so`.
671 ///
672 /// Some possible values:
673 ///
674 /// - so
675 /// - dylib
676 /// - dll
677 #[stable(feature = "env", since = "1.0.0")]
678 pub const DLL_EXTENSION: &'static str = super::os::DLL_EXTENSION;
679
680 /// Specifies the filename suffix used for executable binaries on this
681 /// platform. Example value is `.exe`.
682 ///
683 /// Some possible values:
684 ///
685 /// - .exe
686 /// - .nexe
687 /// - .pexe
688 /// - `""` (an empty string)
689 #[stable(feature = "env", since = "1.0.0")]
690 pub const EXE_SUFFIX: &'static str = super::os::EXE_SUFFIX;
691
692 /// Specifies the file extension, if any, used for executable binaries
693 /// on this platform. Example value is `exe`.
694 ///
695 /// Some possible values:
696 ///
697 /// - exe
698 /// - `""` (an empty string)
699 #[stable(feature = "env", since = "1.0.0")]
700 pub const EXE_EXTENSION: &'static str = super::os::EXE_EXTENSION;
701
702 }
703
704 #[cfg(target_os = "linux")]
705 mod os {
706 pub const FAMILY: &'static str = "unix";
707 pub const OS: &'static str = "linux";
708 pub const DLL_PREFIX: &'static str = "lib";
709 pub const DLL_SUFFIX: &'static str = ".so";
710 pub const DLL_EXTENSION: &'static str = "so";
711 pub const EXE_SUFFIX: &'static str = "";
712 pub const EXE_EXTENSION: &'static str = "";
713 }
714
715 #[cfg(target_os = "macos")]
716 mod os {
717 pub const FAMILY: &'static str = "unix";
718 pub const OS: &'static str = "macos";
719 pub const DLL_PREFIX: &'static str = "lib";
720 pub const DLL_SUFFIX: &'static str = ".dylib";
721 pub const DLL_EXTENSION: &'static str = "dylib";
722 pub const EXE_SUFFIX: &'static str = "";
723 pub const EXE_EXTENSION: &'static str = "";
724 }
725
726 #[cfg(target_os = "ios")]
727 mod os {
728 pub const FAMILY: &'static str = "unix";
729 pub const OS: &'static str = "ios";
730 pub const DLL_PREFIX: &'static str = "lib";
731 pub const DLL_SUFFIX: &'static str = ".dylib";
732 pub const DLL_EXTENSION: &'static str = "dylib";
733 pub const EXE_SUFFIX: &'static str = "";
734 pub const EXE_EXTENSION: &'static str = "";
735 }
736
737 #[cfg(target_os = "freebsd")]
738 mod os {
739 pub const FAMILY: &'static str = "unix";
740 pub const OS: &'static str = "freebsd";
741 pub const DLL_PREFIX: &'static str = "lib";
742 pub const DLL_SUFFIX: &'static str = ".so";
743 pub const DLL_EXTENSION: &'static str = "so";
744 pub const EXE_SUFFIX: &'static str = "";
745 pub const EXE_EXTENSION: &'static str = "";
746 }
747
748 #[cfg(target_os = "dragonfly")]
749 mod os {
750 pub const FAMILY: &'static str = "unix";
751 pub const OS: &'static str = "dragonfly";
752 pub const DLL_PREFIX: &'static str = "lib";
753 pub const DLL_SUFFIX: &'static str = ".so";
754 pub const DLL_EXTENSION: &'static str = "so";
755 pub const EXE_SUFFIX: &'static str = "";
756 pub const EXE_EXTENSION: &'static str = "";
757 }
758
759 #[cfg(target_os = "bitrig")]
760 mod os {
761 pub const FAMILY: &'static str = "unix";
762 pub const OS: &'static str = "bitrig";
763 pub const DLL_PREFIX: &'static str = "lib";
764 pub const DLL_SUFFIX: &'static str = ".so";
765 pub const DLL_EXTENSION: &'static str = "so";
766 pub const EXE_SUFFIX: &'static str = "";
767 pub const EXE_EXTENSION: &'static str = "";
768 }
769
770 #[cfg(target_os = "netbsd")]
771 mod os {
772 pub const FAMILY: &'static str = "unix";
773 pub const OS: &'static str = "netbsd";
774 pub const DLL_PREFIX: &'static str = "lib";
775 pub const DLL_SUFFIX: &'static str = ".so";
776 pub const DLL_EXTENSION: &'static str = "so";
777 pub const EXE_SUFFIX: &'static str = "";
778 pub const EXE_EXTENSION: &'static str = "";
779 }
780
781 #[cfg(target_os = "openbsd")]
782 mod os {
783 pub const FAMILY: &'static str = "unix";
784 pub const OS: &'static str = "openbsd";
785 pub const DLL_PREFIX: &'static str = "lib";
786 pub const DLL_SUFFIX: &'static str = ".so";
787 pub const DLL_EXTENSION: &'static str = "so";
788 pub const EXE_SUFFIX: &'static str = "";
789 pub const EXE_EXTENSION: &'static str = "";
790 }
791
792 #[cfg(target_os = "android")]
793 mod os {
794 pub const FAMILY: &'static str = "unix";
795 pub const OS: &'static str = "android";
796 pub const DLL_PREFIX: &'static str = "lib";
797 pub const DLL_SUFFIX: &'static str = ".so";
798 pub const DLL_EXTENSION: &'static str = "so";
799 pub const EXE_SUFFIX: &'static str = "";
800 pub const EXE_EXTENSION: &'static str = "";
801 }
802
803 #[cfg(target_os = "solaris")]
804 mod os {
805 pub const FAMILY: &'static str = "unix";
806 pub const OS: &'static str = "solaris";
807 pub const DLL_PREFIX: &'static str = "lib";
808 pub const DLL_SUFFIX: &'static str = ".so";
809 pub const DLL_EXTENSION: &'static str = "so";
810 pub const EXE_SUFFIX: &'static str = "";
811 pub const EXE_EXTENSION: &'static str = "";
812 }
813
814 #[cfg(target_os = "windows")]
815 mod os {
816 pub const FAMILY: &'static str = "windows";
817 pub const OS: &'static str = "windows";
818 pub const DLL_PREFIX: &'static str = "";
819 pub const DLL_SUFFIX: &'static str = ".dll";
820 pub const DLL_EXTENSION: &'static str = "dll";
821 pub const EXE_SUFFIX: &'static str = ".exe";
822 pub const EXE_EXTENSION: &'static str = "exe";
823 }
824
825 #[cfg(all(target_os = "nacl", not(target_arch = "le32")))]
826 mod os {
827 pub const FAMILY: &'static str = "unix";
828 pub const OS: &'static str = "nacl";
829 pub const DLL_PREFIX: &'static str = "lib";
830 pub const DLL_SUFFIX: &'static str = ".so";
831 pub const DLL_EXTENSION: &'static str = "so";
832 pub const EXE_SUFFIX: &'static str = ".nexe";
833 pub const EXE_EXTENSION: &'static str = "nexe";
834 }
835 #[cfg(all(target_os = "nacl", target_arch = "le32"))]
836 mod os {
837 pub const FAMILY: &'static str = "unix";
838 pub const OS: &'static str = "pnacl";
839 pub const DLL_PREFIX: &'static str = "lib";
840 pub const DLL_SUFFIX: &'static str = ".pso";
841 pub const DLL_EXTENSION: &'static str = "pso";
842 pub const EXE_SUFFIX: &'static str = ".pexe";
843 pub const EXE_EXTENSION: &'static str = "pexe";
844 }
845
846 #[cfg(target_os = "emscripten")]
847 mod os {
848 pub const FAMILY: &'static str = "unix";
849 pub const OS: &'static str = "emscripten";
850 pub const DLL_PREFIX: &'static str = "lib";
851 pub const DLL_SUFFIX: &'static str = ".so";
852 pub const DLL_EXTENSION: &'static str = "so";
853 pub const EXE_SUFFIX: &'static str = ".js";
854 pub const EXE_EXTENSION: &'static str = "js";
855 }
856
857 #[cfg(target_arch = "x86")]
858 mod arch {
859 pub const ARCH: &'static str = "x86";
860 }
861
862 #[cfg(target_arch = "x86_64")]
863 mod arch {
864 pub const ARCH: &'static str = "x86_64";
865 }
866
867 #[cfg(target_arch = "arm")]
868 mod arch {
869 pub const ARCH: &'static str = "arm";
870 }
871
872 #[cfg(target_arch = "aarch64")]
873 mod arch {
874 pub const ARCH: &'static str = "aarch64";
875 }
876
877 #[cfg(target_arch = "mips")]
878 mod arch {
879 pub const ARCH: &'static str = "mips";
880 }
881
882 #[cfg(target_arch = "powerpc")]
883 mod arch {
884 pub const ARCH: &'static str = "powerpc";
885 }
886
887 #[cfg(target_arch = "powerpc64")]
888 mod arch {
889 pub const ARCH: &'static str = "powerpc64";
890 }
891
892 #[cfg(target_arch = "le32")]
893 mod arch {
894 pub const ARCH: &'static str = "le32";
895 }
896
897 #[cfg(target_arch = "asmjs")]
898 mod arch {
899 pub const ARCH: &'static str = "asmjs";
900 }
901
902 #[cfg(test)]
903 mod tests {
904 use prelude::v1::*;
905 use super::*;
906
907 use iter::repeat;
908 use rand::{self, Rng};
909 use ffi::{OsString, OsStr};
910 use path::{Path, PathBuf};
911
912 fn make_rand_name() -> OsString {
913 let mut rng = rand::thread_rng();
914 let n = format!("TEST{}", rng.gen_ascii_chars().take(10)
915 .collect::<String>());
916 let n = OsString::from(n);
917 assert!(var_os(&n).is_none());
918 n
919 }
920
921 fn eq(a: Option<OsString>, b: Option<&str>) {
922 assert_eq!(a.as_ref().map(|s| &**s), b.map(OsStr::new).map(|s| &*s));
923 }
924
925 #[test]
926 fn test_set_var() {
927 let n = make_rand_name();
928 set_var(&n, "VALUE");
929 eq(var_os(&n), Some("VALUE"));
930 }
931
932 #[test]
933 fn test_remove_var() {
934 let n = make_rand_name();
935 set_var(&n, "VALUE");
936 remove_var(&n);
937 eq(var_os(&n), None);
938 }
939
940 #[test]
941 fn test_set_var_overwrite() {
942 let n = make_rand_name();
943 set_var(&n, "1");
944 set_var(&n, "2");
945 eq(var_os(&n), Some("2"));
946 set_var(&n, "");
947 eq(var_os(&n), Some(""));
948 }
949
950 #[test]
951 fn test_var_big() {
952 let mut s = "".to_string();
953 let mut i = 0;
954 while i < 100 {
955 s.push_str("aaaaaaaaaa");
956 i += 1;
957 }
958 let n = make_rand_name();
959 set_var(&n, &s);
960 eq(var_os(&n), Some(&s));
961 }
962
963 #[test]
964 fn test_self_exe_path() {
965 let path = current_exe();
966 assert!(path.is_ok());
967 let path = path.unwrap();
968
969 // Hard to test this function
970 assert!(path.is_absolute());
971 }
972
973 #[test]
974 fn test_env_set_get_huge() {
975 let n = make_rand_name();
976 let s = repeat("x").take(10000).collect::<String>();
977 set_var(&n, &s);
978 eq(var_os(&n), Some(&s));
979 remove_var(&n);
980 eq(var_os(&n), None);
981 }
982
983 #[test]
984 fn test_env_set_var() {
985 let n = make_rand_name();
986
987 let mut e = vars_os();
988 set_var(&n, "VALUE");
989 assert!(!e.any(|(k, v)| {
990 &*k == &*n && &*v == "VALUE"
991 }));
992
993 assert!(vars_os().any(|(k, v)| {
994 &*k == &*n && &*v == "VALUE"
995 }));
996 }
997
998 #[test]
999 fn test() {
1000 assert!((!Path::new("test-path").is_absolute()));
1001
1002 current_dir().unwrap();
1003 }
1004
1005 #[test]
1006 #[cfg(windows)]
1007 fn split_paths_windows() {
1008 fn check_parse(unparsed: &str, parsed: &[&str]) -> bool {
1009 split_paths(unparsed).collect::<Vec<_>>() ==
1010 parsed.iter().map(|s| PathBuf::from(*s)).collect::<Vec<_>>()
1011 }
1012
1013 assert!(check_parse("", &mut [""]));
1014 assert!(check_parse(r#""""#, &mut [""]));
1015 assert!(check_parse(";;", &mut ["", "", ""]));
1016 assert!(check_parse(r"c:\", &mut [r"c:\"]));
1017 assert!(check_parse(r"c:\;", &mut [r"c:\", ""]));
1018 assert!(check_parse(r"c:\;c:\Program Files\",
1019 &mut [r"c:\", r"c:\Program Files\"]));
1020 assert!(check_parse(r#"c:\;c:\"foo"\"#, &mut [r"c:\", r"c:\foo\"]));
1021 assert!(check_parse(r#"c:\;c:\"foo;bar"\;c:\baz"#,
1022 &mut [r"c:\", r"c:\foo;bar\", r"c:\baz"]));
1023 }
1024
1025 #[test]
1026 #[cfg(unix)]
1027 fn split_paths_unix() {
1028 fn check_parse(unparsed: &str, parsed: &[&str]) -> bool {
1029 split_paths(unparsed).collect::<Vec<_>>() ==
1030 parsed.iter().map(|s| PathBuf::from(*s)).collect::<Vec<_>>()
1031 }
1032
1033 assert!(check_parse("", &mut [""]));
1034 assert!(check_parse("::", &mut ["", "", ""]));
1035 assert!(check_parse("/", &mut ["/"]));
1036 assert!(check_parse("/:", &mut ["/", ""]));
1037 assert!(check_parse("/:/usr/local", &mut ["/", "/usr/local"]));
1038 }
1039
1040 #[test]
1041 #[cfg(unix)]
1042 fn join_paths_unix() {
1043 fn test_eq(input: &[&str], output: &str) -> bool {
1044 &*join_paths(input.iter().cloned()).unwrap() ==
1045 OsStr::new(output)
1046 }
1047
1048 assert!(test_eq(&[], ""));
1049 assert!(test_eq(&["/bin", "/usr/bin", "/usr/local/bin"],
1050 "/bin:/usr/bin:/usr/local/bin"));
1051 assert!(test_eq(&["", "/bin", "", "", "/usr/bin", ""],
1052 ":/bin:::/usr/bin:"));
1053 assert!(join_paths(["/te:st"].iter().cloned()).is_err());
1054 }
1055
1056 #[test]
1057 #[cfg(windows)]
1058 fn join_paths_windows() {
1059 fn test_eq(input: &[&str], output: &str) -> bool {
1060 &*join_paths(input.iter().cloned()).unwrap() ==
1061 OsStr::new(output)
1062 }
1063
1064 assert!(test_eq(&[], ""));
1065 assert!(test_eq(&[r"c:\windows", r"c:\"],
1066 r"c:\windows;c:\"));
1067 assert!(test_eq(&["", r"c:\windows", "", "", r"c:\", ""],
1068 r";c:\windows;;;c:\;"));
1069 assert!(test_eq(&[r"c:\te;st", r"c:\"],
1070 r#""c:\te;st";c:\"#));
1071 assert!(join_paths([r#"c:\te"st"#].iter().cloned()).is_err());
1072 }
1073 }