Using standard I/O as the source or destination
Ascp can use standard input (stdin
) as the source or
standard output (stdout
) as the destination for a transfer. The syntax depends on
the number of files in your transfer; for single files use stdio:// and for
multiple files use stdio-tar://. The transfer is authenticated by using SSH or
a transfer token.
Named pipes
stdio
destination, with the syntax
stdio:///path for single files, or
stdio-tar:///path for multiple files, where
path is the path of the named pipe. If a docroot is configured on the
destination, then the transfer goes to the named pipe
docroot/path.Single file transfers
To upload data that is piped into stdin
, set the source as
stdio:///?fsize, where fsize is the
number of bytes (as a decimal) that are received from stdin
. The destination is set
as the path and file name. The file modification time is set to the time at which the upload starts.
Standard input must transfer the exact amount of data that is set by fsize. If
more or less data is received by the server, an error is generated.
To download data and pipe it into stdout
, set the destination as
stdio://.
Restrictions:
- stdio:// cannot be used for persistent sessions. Use stdio-tar:// instead.
- Only
--overwrite=always
or--overwrite=never
are supported by stdio://. The behavior of--overwrite=diff
and--overwrite=diff+older
is undefined. - When the size (
?fsize
) is not specified, the file is managed by the growing files feature where an End-of-File (EOF) on readingstdin
will signify that the growing file is complete.
Single-file Transfer Examples:
- Upload 1025 bytes of data from the client
stdin
to /remote-dir on the server at 10.0.0.2. Save the data as the file newfile. Transfer at 100 Mbps.cat myfile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio:///newfile?1025 /remote-dir
- Download the file remote_file from the server at 10.0.0.2 to
stdout
on the client. Transfer at 100 Mbps.ascp -l 100m --mode=recv --user=username --host=10.0.0.2 remote_file stdio://
- Upload the file local_file to the server at 10.0.0.2 to the named pipe
/tmp/outpipe. Transfer at 100
Mbps.
ascp -l 100m --mode=send --user=username --host=10.0.0.2 local_file stdio:////tmp/outpipe
Multi-File transfers
Ascp can transfer one or more files in an encoded, streamed interface, similar to single file transfers. The primary difference is that the stream includes headers that demarcate data from individual files.
To upload files that are piped into stdin
, set the source as
stdio-tar://. The file modification time is set to the time at which the upload
starts.
File
can
be the file name or file path, Size
is the size of the file in bytes, and
Offset
is an optional parameter that sets where in the destination file to begin
overwriting with the raw inline data: [0 - n blank lines]
File: /path/to/file_1
Size: file_size
Offset: bytes
file_1 data
[0 - n blank lines]
File: /path/to/file_2
Size: file_size
file 2 data
...
To download one or more files to stdout
, set the destination as
stdio-tar://. Normal status output to stdout
is suppressed
during downloads because the transfer output is streamed to stdout
. The data sent
to stdout
has the same encoding as described for uploads.
To download to a named pipe, set the destination to stdio-tar:////path, where path is the path of the named pipe.
When an offset is specified, the bytes that are sent replace the existing bytes in the destination file (if it exists). The bytes added to the destination file can extend beyond the current file size. If no offset is set, the bytes overwrite the file if overwrite conditions are met.
Restrictions:
- When downloading to stdio-tar://, the source list must consist of individual files only. Directories are not allowed.
- Only
--overwrite=always
or--overwrite=never
are supported by stdio-tar://. The behavior of--overwrite=diff
and--overwrite=diff+older
is undefined. - Offsets are only supported if the destination files are located in the native file system. Offsets are not supported for cloud destinations.
Multi-file transfer examples:
- Upload two files, myfile1 (1025 bytes) and myfile2 (20
bytes), to /remote-dir on the server at 10.0.0.2. Transfer at 100
Mbps.
Where sourcefile contains the following:cat sourcefile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio-tar:// /remote-dir
File: myfile1 Size: 1025 << 1025 bytes of data>> File: myfile2 Size: 20 <<20 bytes of data>>
- Uploading multiple files from
stdin
by using a persistent session is the same as a nonpersistent session. - Update bytes 10-19 in file /remote-dir/myfile1 on the server at 10.0.0.2 at
100
Mbps.
Where sourcefile contains the following:cat sourcefile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio-tar:// /remote-dir
File: myfile1 Size: 10 Offset: 10 << 10 bytes of data>>
- Upload two files, myfile1 and myfile2, to the named
pipe /tmp/mypipe (streaming output) on the server at 10.0.0.2. Transfer at 100
Mbps.
This sends an encoded stream of myfile1 and myfile2 (with the format of sourcefile in the upload example) to the pipe /tmp/mypipe. If /tmp/mypipe does not exist, it is created.ascp -l 100m --mode=send --user=username --host=10.0.0.2 myfile1 myfile2 stdio-tar:////tmp/mypipe
- Download the files from the previous example from 10.0.0.2 to
stdout
. Transfer at 100 Mbps.
Standard output receives data identical to sourcefile in the upload example.ascp -l 100m --mode=recv --user=username --host=10.0.0.2 myfile1 myfile2 stdio-tar://
- Download /tmp/myfile1 and /tmp/myfile2 to
stdout
by using a persistent session. Start the persistent session, which listens on management port 12345:ascp -l 100m --mode=recv --keepalive -M 12345 --user=username --host=10.0.0.2 stdio-tar://
Send the following in through management port 12345:
The destination must be a file name; file paths are not supported.FASPMGR 2 Type: START Source: /tmp/myfile1 Destination: mynewfile1 FASPMGR 2 Type: START Source: /tmp/myfile2 Destination: mynewfile2 FASPMGR 2 Type: DONE
Standard out receives the transferred data with the following syntax:
File: mynewfile1 Size: file_size mynewfile1_data File: mynewfile2 Size: file_size mynewfile2_data
- Upload two files, myfile1 and myfile2, to named pipe
/tmp/mypipe on the server at 10.0.0.2. Transfer at 100
Mbps.
ascp -l 100m --mode=send --user=username --host=10.0.0.2 myfile1 myfile2 stdio-tar:////tmp/mypipe
If file/tmp/mypipe does not exist, it is created.
- Upload two files, myfile1 (1025 bytes) and myfile2 (20
bytes) from stdio and regenerate the stream on the destination to send out through the named pipe
/tmp/mypipe on the server at 10.0.0.2. Transfer at 100
Mbps.
Where sourcefile contains the following:cat sourcefile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio-tar:// stdio-tar:////tmp/pipe
File: myfile1 Size: 1025 << 1025 bytes of data>> File: myfile2 Size: 20 <<20 bytes of data>>