filetime

https://docs.rs/filetime/0.2.27/filetime/
Admin
filetime is a Rust library providing platform-agnostic inspection and manipulation of file...
Tokens:5,219
Snippets:52
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Filetime Crate Usage Example

Source: https://docs.rs/filetime/0.2.27/filetime/index.html

A basic example demonstrating how to use the filetime crate to get and print file modification and access times.

```APIDOC
## Usage

```rust
use std::fs;
use filetime::FileTime;

let metadata = fs::metadata("foo.txt").unwrap();

let mtime = FileTime::from_last_modification_time(&metadata);
println!("{}", mtime);

let atime = FileTime::from_last_access_time(&metadata);
assert!(mtime < atime);

// Inspect values that can be interpreted across platforms
println!("{}", mtime.unix_seconds());
println!("{}", mtime.nanoseconds());

// Print the platform-specific value of seconds
println!("{}", mtime.seconds());
```
```

--------------------------------

### Filetime Crate Installation

Source: https://docs.rs/filetime/0.2.27/filetime/index.html

Instructions on how to add the filetime crate to your Rust project's Cargo.toml file.

```APIDOC
## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
filetime = "0.2"
```
```

--------------------------------

### Get Current File Modification Time

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Use `FileTime::now()` to get the current system time for setting file modification times. This is equivalent to `FileTime::from_system_time(SystemTime::now())`.

```rust
filetime::set_file_mtime(path, FileTime::now())?;
```

--------------------------------

### Inspect File Timestamps with filetime

Source: https://docs.rs/filetime/0.2.27/filetime/index.html

Use this code to get and print the last modification and access times of a file. It shows how to convert metadata timestamps to `FileTime` objects and access their Unix seconds and nanoseconds.

```rust
use std::fs;
use filetime::FileTime;

let metadata = fs::metadata("foo.txt").unwrap();

let mtime = FileTime::from_last_modification_time(&metadata);
println!("{}", mtime);

let atime = FileTime::from_last_access_time(&metadata);
assert!(mtime < atime);

// Inspect values that can be interpreted across platforms
println!("{}", mtime.unix_seconds());
println!("{}", mtime.nanoseconds());

// Print the platform-specific value of seconds
println!("{}", mtime.seconds());
```

--------------------------------

### Get Nanoseconds from FileTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Retrieve the nanosecond precision of a `FileTime`. The value is always less than one billion and represents the fractional part of a second.

```rust
pub const fn nanoseconds(&self) -> u32
```

--------------------------------

### Get Unix Seconds from FileTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Retrieve the whole number of seconds from a `FileTime` relative to the Unix epoch (January 1, 1970). This differs from `seconds()` on Windows platforms.

```rust
pub const fn unix_seconds(&self) -> i64
```

--------------------------------

### Get Seconds from FileTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Retrieve the whole number of seconds from a `FileTime`. The meaning of this value is platform-specific: Unix typically uses the 1970 epoch, while Windows uses the 1601 epoch.

```rust
pub const fn seconds(&self) -> i64
```

--------------------------------

### PartialEq Implementation

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Details the equality comparison methods for `FileTime`.

```APIDOC
## impl PartialEq for FileTime

### `eq(&self, other: &FileTime) -> bool`

Tests if `self` and `other` `FileTime` values are equal. This method is used by the `==` operator.

### `ne(&self, other: &Rhs) -> bool`

Tests for inequality (`!=`). The default implementation is generally sufficient and should not be overridden without strong justification.
```

--------------------------------

### FileTime Creation Methods

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Methods for creating new FileTime instances, including zero time, current system time, and from various time representations.

```APIDOC
## FileTime Creation Methods

### `zero()`

Creates a new timestamp representing a 0 time. Useful for creating the base of a `cmp::max` chain of times.

```rust
pub const fn zero() -> FileTime
```

### `now()`

Creates a new timestamp representing the current system time. Equivalent to `FileTime::from_system_time(SystemTime::now())`.

```rust
pub fn now() -> FileTime
```

### `from_unix_time(seconds: i64, nanos: u32)`

Creates a new instance of `FileTime` with a number of seconds and nanoseconds relative to the Unix epoch (1970-01-01T00:00:00Z).

Note: On Windows, the native timestamp is relative to January 1, 1601, so the returned `seconds` may not match the input.

```rust
pub const fn from_unix_time(seconds: i64, nanos: u32) -> FileTime
```

### `from_last_modification_time(meta: &Metadata)`

Creates a new timestamp from the last modification time listed in the specified metadata (`mtime` on Unix, `ftLastWriteTime` on Windows).

```rust
pub fn from_last_modification_time(meta: &Metadata) -> FileTime
```

### `from_last_access_time(meta: &Metadata)`

Creates a new timestamp from the last access time listed in the specified metadata (`atime` on Unix, `ftLastAccessTime` on Windows).

```rust
pub fn from_last_access_time(meta: &Metadata) -> FileTime
```

### `from_creation_time(meta: &Metadata)`

Creates a new timestamp from the creation time listed in the specified metadata (`birthtime` on Unix, `ftCreationTime` on Windows). Returns `None` if not available.

```rust
pub fn from_creation_time(meta: &Metadata) -> Option<FileTime>
```

### `from_system_time(time: SystemTime)`

Creates a new timestamp from the given `SystemTime`. Errors if the `SystemTime` is before 1601-01-01T00:00:00Z on Windows.

```rust
pub fn from_system_time(time: SystemTime) -> FileTime
```
```

--------------------------------

### FileTime Methods

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Provides documentation for the core methods of the FileTime struct.

```APIDOC
## FileTime Methods

### `max(self, other: Self) -> Self`

Compares and returns the maximum of two `FileTime` values.

### `min(self, other: Self) -> Self`

Compares and returns the minimum of two `FileTime` values.

### `clamp(self, min: Self, max: Self) -> Self`

Restricts a `FileTime` value to a certain interval defined by `min` and `max`.
```

--------------------------------

### Create FileTime from Unix Epoch

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Construct a `FileTime` from seconds and nanoseconds relative to the Unix epoch. Note that on Windows, the native timestamp is relative to 1601-01-01, so the `seconds` value may differ from the input.

```rust
pub const fn from_unix_time(seconds: i64, nanos: u32) -> FileTime
```

--------------------------------

### PartialOrd Implementation

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Details the partial ordering comparison methods for `FileTime`.

```APIDOC
## impl PartialOrd for FileTime

### `partial_cmp(&self, other: &FileTime) -> Option<Ordering>`

This method returns an `Ordering` between `self` and `other` values if one exists.

### `lt(&self, other: &Rhs) -> bool`

Tests for less than (`<`) comparison between `self` and `other`.

### `le(&self, other: &Rhs) -> bool`

Tests for less than or equal to (`<=`) comparison between `self` and `other`.

### `gt(&self, other: &Rhs) -> bool`

Tests for greater than (`>`) comparison between `self` and `other`.

### `ge(&self, other: &Rhs) -> bool`

Tests for greater than or equal to (`>=`) comparison between `self` and `other`.
```

--------------------------------

### Create FileTime from SystemTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Convert a `SystemTime` into a `FileTime`. This function will error if the `SystemTime` represents a time before Windows' native file time epoch (1601-01-01T00:00:00Z).

```rust
pub fn from_system_time(time: SystemTime) -> FileTime
```

--------------------------------

### Add filetime to Cargo.toml

Source: https://docs.rs/filetime/0.2.27/filetime/index.html

Add this to your `Cargo.toml` file to include the filetime crate in your project dependencies.

```toml
[dependencies]
filetime = "0.2"
```

--------------------------------

### From SystemTime for FileTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

The `From<SystemTime>` trait implementation allows direct conversion from `SystemTime` to `FileTime`.

```rust
fn from(time: SystemTime) -> FileTime
```

--------------------------------

### Blanket Implementations

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Details blanket implementations available for `FileTime` through generic traits.

```APIDOC
## Blanket Implementations

### `impl<T> Any for T`

#### `type_id(&self) -> TypeId`

Gets the `TypeId` of `self`.

### `impl<T> Borrow<T> for T`

#### `borrow(&self) -> &T`

Immutably borrows from an owned value.

### `impl<T> BorrowMut<T> for T`

#### `borrow_mut(&mut self) -> &mut T`

Mutably borrows from an owned value.

### `impl<T> CloneToUninit for T`

#### `unsafe fn clone_to_uninit(&self, dest: *mut u8)`

Performs copy-assignment from `self` to `dest`. This is a nightly-only experimental API.

### `impl<T> From<T> for T`

#### `from(t: T) -> T`

Returns the argument unchanged.

### `impl<T, U> Into<U> for T`

#### `into(self) -> U`

Calls `U::from(self)`. The conversion behavior is determined by the `From<T> for U` implementation.

### `impl<T> ToOwned for T`

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `to_owned(&self) -> T`

Creates owned data from borrowed data, usually by cloning.

#### `clone_into(&self, target: &mut T)`

Uses borrowed data to replace owned data, usually by cloning.

### `impl<T> ToString for T`

#### `to_string(&self) -> String`

Converts the given value to a `String`.

### `impl<T, U> TryFrom<U> for T`

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`

Performs the conversion.

### `impl<T, U> TryInto<U> for T`

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`

Performs the conversion.
```

--------------------------------

### Debug and Display for FileTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Implementations for `Debug` and `Display` traits enable formatted output for `FileTime` instances.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

--------------------------------

### Create FileTime from Metadata

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Extract file timestamps (modification, access, creation) from `Metadata`. `from_creation_time` may return `None` on Unix platforms that do not support birthtime.

```rust
pub fn from_last_modification_time(meta: &Metadata) -> FileTime
```

```rust
pub fn from_last_access_time(meta: &Metadata) -> FileTime
```

```rust
pub fn from_creation_time(meta: &Metadata) -> Option<FileTime>
```

--------------------------------

### Auto Trait Implementations

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Lists the automatic trait implementations for `FileTime`.

```APIDOC
## Auto Trait Implementations

### `impl Freeze for FileTime`

### `impl RefUnwindSafe for FileTime`

### `impl Send for FileTime`

### `impl Sync for FileTime`

### `impl Unpin for FileTime`

### `impl UnwindSafe for FileTime`
```

--------------------------------

### Clone FileTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Implementations for `Clone` and `clone_from` allow for creating duplicates of `FileTime` values.

```rust
fn clone(&self) -> FileTime
```

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### FileTime Zero Timestamp

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Create a `FileTime` representing a zero timestamp. This is useful as a base for comparisons, such as in `cmp::max` chains.

```rust
pub const fn zero() -> FileTime
```

--------------------------------

### FileTime Inspection

Source: https://docs.rs/filetime

How to inspect file timestamps using the FileTime struct.

```APIDOC
## FileTime Inspection

### Description
Use the FileTime struct to inspect last modification and access times from file metadata.

### Usage Example
```rust
use std::fs;
use filetime::FileTime;

let metadata = fs::metadata("foo.txt").unwrap();
let mtime = FileTime::from_last_modification_time(&metadata);
println!("{}", mtime.unix_seconds());
```
```

--------------------------------

### FileTime Accessor Methods

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Methods for retrieving the time components from a FileTime instance.

```APIDOC
## FileTime Accessor Methods

### `seconds()`

Returns the whole number of seconds represented by this timestamp. The meaning is platform-specific (Unix: relative to 1970, Windows: relative to 1601).

```rust
pub const fn seconds(&self) -> i64
```

### `unix_seconds()`

Returns the whole number of seconds represented by this timestamp, relative to the Unix epoch (January 1, 1970).

Note: This may differ from `seconds()` on Windows platforms.

```rust
pub const fn unix_seconds(&self) -> i64
```

### `nanoseconds()`

Returns the nanosecond precision of this timestamp (0 to 999,999,999).

```rust
pub const fn nanoseconds(&self) -> u32
```
```

--------------------------------

### FileTime Trait Implementations

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Common trait implementations for the FileTime struct, including Clone, Debug, Display, From, Hash, and Ord.

```APIDOC
## FileTime Trait Implementations

### `Clone`

Allows creating a duplicate of a `FileTime` value.

```rust
impl Clone for FileTime
```

### `Debug`

Provides a developer-friendly representation of the `FileTime` value for debugging.

```rust
impl Debug for FileTime
```

### `Display`

Provides a user-friendly string representation of the `FileTime` value.

```rust
impl Display for FileTime
```

### `From<SystemTime>`

Enables conversion from `std::time::SystemTime` to `FileTime`.

```rust
impl From<SystemTime> for FileTime
```

### `Hash`

Allows `FileTime` values to be used in hash-based collections.

```rust
impl Hash for FileTime
```

### `Ord`

Enables ordering comparisons between `FileTime` values.

```rust
impl Ord for FileTime
```
```

--------------------------------

### Hash and Ord for FileTime

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Implementations for `Hash` and `Ord` traits enable hashing and comparison operations on `FileTime` values.

```rust
fn hash<__H: Hasher>(&self, state: &mut __H)
```

```rust
fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher,
Self: Sized,
```

```rust
fn cmp(&self, other: &FileTime) -> Ordering
```

--------------------------------

### Set File Access and Modification Times in Rust

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_times.html

Use this function to set the atime and mtime metadata fields for a file on the local filesystem. It returns a Result, indicating success or failure.

```rust
pub fn set_file_times<P>(p: P, atime: FileTime, mtime: FileTime) -> Result<()>
where
    P: AsRef<Path>,

```

--------------------------------

### Set file access time with set_file_atime

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_atime.html

Updates the atime metadata field for a file. May perform multiple syscalls if the platform does not support updating atime independently.

```rust
pub fn set_file_atime<P>(p: P, atime: FileTime) -> Result<()>
where
    P: AsRef<Path>,
```

--------------------------------

### set_file_atime

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_atime.html

Sets the last access time for a file on the filesystem.

```APIDOC
## set_file_atime

### Description
Sets the last access time for a file on the filesystem. This function updates the `atime` metadata field for a file on the local filesystem.

### Parameters
#### Path Parameters
- **p** (AsRef<Path>) - Required - The path to the file to update.

#### Request Body
- **atime** (FileTime) - Required - The new access time to set.

### Response
#### Success Response (200)
- **Result<()>** - Returns an empty result on success, or an error if the operation fails.
```

--------------------------------

### FileTime Struct

Source: https://docs.rs/filetime/0.2.27/filetime/struct.FileTime.html

Represents a timestamp for a file. The internal value is platform-specific, but comparisons and stringification are significant on the same platform.

```APIDOC
## Struct FileTime

### Description
A helper structure to represent a timestamp for a file. The actual value contained within is platform-specific and does not have the same meaning across platforms, but comparisons and stringification can be significant among the same platform.

### Fields
(Private fields, not exposed)
```

--------------------------------

### FileTime Struct

Source: https://docs.rs/filetime/0.2.27/filetime/index.html

Information about the FileTime struct, which is a helper structure to represent a timestamp for a file.

```APIDOC
## Structs

### FileTime

A helper structure to represent a timestamp for a file.
```

--------------------------------

### File Timestamp Modification Functions

Source: https://docs.rs/filetime/0.2.27/filetime/index.html

Functions available in the filetime crate for setting various timestamps of files and symlinks.

```APIDOC
## Functions

### `set_file_atime`

Set the last access time for a file on the filesystem.

### `set_file_handle_times`

Set the last access and modification times for a file handle.

### `set_file_mtime`

Set the last modification time for a file on the filesystem.

### `set_file_times`

Set the last access and modification times for a file on the filesystem.

### `set_symlink_file_times`

Set the last access and modification times for a file on the filesystem. This function does not follow symlink.
```

--------------------------------

### Set file handle timestamps

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_handle_times.html

Updates the access and modification times for a given file handle. If an argument is set to None, that specific timestamp remains unchanged.

```rust
pub fn set_file_handle_times(
    f: &File,
    atime: Option<FileTime>,
    mtime: Option<FileTime>,
) -> Result<()>
```

--------------------------------

### Set Symlink File Times

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_symlink_file_times.html

Sets the last access and modification times for a file. This function does not follow symlinks. It modifies the atime and mtime metadata fields.

```rust
pub fn set_symlink_file_times<
    P,
>(
    p: P,
    atime: FileTime,
    mtime: FileTime,
) -> Result<()>
where
    P: AsRef<Path>,

```

--------------------------------

### Set file modification time

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_mtime.html

Updates the mtime metadata for a file. Requires a path and a FileTime object.

```rust
pub fn set_file_mtime<P>(p: P, mtime: FileTime) -> Result<()>
where
    P: AsRef<Path>,
```

--------------------------------

### set_file_handle_times

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_handle_times.html

Sets the last access and modification times for a file handle.

```APIDOC
## set_file_handle_times

### Description
Sets the last access and modification times for a file handle. If None is specified for a time, it will not be updated. If both are None, no action is taken.

### Parameters
- **f** (&File) - Required - The file handle to modify.
- **atime** (Option<FileTime>) - Optional - The new access time.
- **mtime** (Option<FileTime>) - Optional - The new modification time.

### Response
- **Result<()>** - Returns an empty result on success, or an error if the operation fails.
```

--------------------------------

### set_file_times

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_times.html

Sets the last access and modification times for a file on the filesystem.

```APIDOC
## set_file_times

### Description
Sets the last access and modification times for a file on the local filesystem.

### Parameters
- **p** (AsRef<Path>) - Required - The path to the file.
- **atime** (FileTime) - Required - The new access time.
- **mtime** (FileTime) - Required - The new modification time.

### Response
- **Result<()>** - Returns an empty result on success, or an error if the operation fails.
```

--------------------------------

### set_symlink_file_times

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_symlink_file_times.html

Sets the last access and modification times for a file. This function does not follow symlinks.

```APIDOC
## set_symlink_file_times

### Description
Sets the last access and modification times for a file on the filesystem. This function does not follow symlink.
This function will set the `atime` and `mtime` metadata fields for a file on the local filesystem, returning any error encountered.

### Method
`pub fn` (Rust function signature implies a programmatic call, not a direct HTTP method)

### Endpoint
N/A (This is a Rust library function, not a REST API endpoint)

### Parameters
#### Path Parameters
- **p** (P) - Required - The path to the file.

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use filetime::FileTime;
use std::path::Path;

// Assuming 'file_path' is a Path and 'atime_val', 'mtime_val' are FileTime instances
// let result = set_symlink_file_times(file_path, atime_val, mtime_val);
```

### Response
#### Success Response (Result::Ok)
- **()** - Indicates the operation was successful.

#### Error Response (Result::Err)
- **std::io::Error** - An error encountered during the file operation.

#### Response Example
```rust
// Success:
// Ok(())

// Error:
// Err(std::io::Error { kind: ... })
```
```

--------------------------------

### Set File Modification Time

Source: https://docs.rs/filetime/0.2.27/filetime/fn.set_file_mtime.html

This function sets the last modification time for a file on the filesystem. It returns a Result, indicating success or failure.

```APIDOC
## POST /set_file_mtime

### Description
Set the last modification time for a file on the filesystem. This function will set the `mtime` metadata field for a file on the local filesystem, returning any error encountered.

### Method
POST

### Endpoint
/set_file_mtime

### Parameters
#### Path Parameters
- **p** (P) - Required - The path to the file.
- **mtime** (FileTime) - Required - The new modification time to set.

### Request Body
```json
{
  "p": "string",
  "mtime": "FileTime"
}
```

### Response
#### Success Response (200)
- **Ok** (Result) - Indicates successful modification.

#### Response Example
```json
{
  "Ok": null
}
```

### Platform Support
Where supported this will attempt to issue just one syscall to update only the `mtime`, but where not supported this may issue one syscall to learn the existing `atime` so only the `mtime` can be configured.
```
Tokens:
Raw