NAME

Command::Run::Tmpfile - Temporary file with /dev/fd path access

SYNOPSIS

use Command::Run::Tmpfile;

my $tmp = Command::Run::Tmpfile->new;
$tmp->write("some data")->flush;

# Pass to external command as file argument
system("cat", $tmp->path);  # /dev/fd/N

# Read back
$tmp->rewind;
my $data = do { local $/; my $fh = $tmp->fh; <$fh> };

DESCRIPTION

This module provides an anonymous temporary file that can be accessed via /dev/fd/N or /proc/self/fd/N path. The file is automatically deleted when the object is destroyed.

This is useful when you need to pass data to external commands that require file arguments rather than stdin.

METHODS

new([raw => bool])

Create a new temporary file object.

By default the underlying file handle is opened with the :encoding(utf8) layer, so character strings are encoded to UTF-8 on write and decoded on read.

When raw is true, the :raw layer is used instead, making the file a transparent byte container: whatever bytes are written are stored and read back unchanged. Use this when you write data that is already a byte stream (for example the output of an external command captured with qx//, or the result of encode 'utf8', ...), to avoid double encoding.

my $tmp = Command::Run::Tmpfile->new(raw => 1);
$tmp->write($bytes)->rewind;
system("cat", $tmp->path);  # bytes pass through unchanged

Note that raw means :raw (no conversion at all), which is distinct from the :utf8 layer used by Command::Run's nofork+raw execution mode.

write(@data)

Write data to the temporary file. Returns the object for method chaining.

flush()

Flush the file buffer. Returns the object for method chaining.

rewind()

Seek to the beginning of the file. Returns the object for method chaining.

reset()

Rewind and truncate the file (clear contents). Returns the object for method chaining.

fh()

Return the underlying file handle.

fd()

Return the file descriptor number.

path()

Return the file descriptor path (e.g., /dev/fd/3). On the first call to new, the module probes for a usable file descriptor path by checking /proc/self/fd/N and /dev/fd/N for the just-allocated fd. If neither is available (for example on FreeBSD without fdescfs mounted), path returns undef.

SEE ALSO

Command::Run

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright 2026 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.