Differences
This shows you the differences between the selected revisions of the page.
| transfer_mode 2013-10-25 | transfer_mode 2024-05-28 (current) | ||
| Line 1: | Line 1: | ||
| ====== Transfer Modes ====== | ====== Transfer Modes ====== | ||
| - | As different platforms (operating systems) uses different format of text files, many transfer protocols support special mode for transferring text files (called text or ASCII mode). In the mode the file is not only transferred, but also converted to format used by the target platform. The mode must not be used for binary files (including document files from modern text processors, like Microsoft Word), as they must be transferred without modification. | + | As different platforms (operating systems) use different format of text files, many transfer protocols support special mode for transferring text files (called text or ASCII mode). In the mode the file is not only transferred, but also converted to format used by the target platform. The mode must not be used for binary files (including document files from modern text processors, like Microsoft Word), as they must be transferred without modification. |
| ===== Available Modes ===== | ===== Available Modes ===== | ||
| Line 8: | Line 8: | ||
| Files not matching the mask are transferred using //Binary// mode. | Files not matching the mask are transferred using //Binary// mode. | ||
| - | ===== Server-side Text File Format ===== | + | ===== [[eol]] Server-side Text File Format ===== |
| There are two options how to support text mode transfers. The first option is that the client (WinSCP) knows directly the text file format used by the server and converts the file to the format before transfer. The second option is that there is some in advance agreed canonical format to which the client converts the file before transfer and from which the server converts it (if necessary) after transfer to its own format. | There are two options how to support text mode transfers. The first option is that the client (WinSCP) knows directly the text file format used by the server and converts the file to the format before transfer. The second option is that there is some in advance agreed canonical format to which the client converts the file before transfer and from which the server converts it (if necessary) after transfer to its own format. | ||
| - | The second option is more universal, but it is supported only by [[sftp|SFTP-4]] and newer and [[FTP]]((Actually with FTP, file is uploaded unmodified, anticipating the server to be able to convert it to its own format.)). | + | The second option is more universal, but it is supported only by [[sftp|SFTP-4]] and newer and [[FTP]].((Actually with FTP, file is uploaded unmodified, anticipating the server to be able to convert it to its own format.)) |
| - | The first option is used by WinSCP for [[SCP]] and SFTP-3 and older protocols. It this case the client (WinSCP) must directly know and support the server-side format. Generally there are plenty of text file formats, almost every platform has it own format. WinSCP supports two of the most used formats, Unix and Windows. You can select between them on //[[ui_login_environment#end-of-line_characters|Environment page]]// of Login Dialog. As most SSH servers are run on Unix system, generally you may leave the default Unix format. | + | The first option is used by WinSCP for [[SCP]] and SFTP-3 and older protocols. It this case the client (WinSCP) must directly know and support the server-side format. Generally there are plenty of text file formats, almost every platform has it own format. WinSCP supports two of the most used formats, Unix and Windows. You can select between them on //[[ui_login_environment#eol|Environment page]]// of Advanced Site Settings dialog. As most SSH (SFTP and SCP) servers and many FTP servers are run on Unix system, generally you may leave the default Unix format. |
| + | |||
| + | [[WebDAV]] and [[S3]] protocols do not allow selecting transfer mode. | ||
| ===== Editing Binary Files ===== | ===== Editing Binary Files ===== | ||
| - | Learn how to edit [[task_edit#editing_binary_files|remote binary file locally]]. | + | Learn how to edit [[task_edit#binary|remote binary file locally]]. |
| - | ===== Transferring Large Text Files with SCP Protocol ===== | + | ===== [[changing]] Changing Transfer Mode ===== |
| - | Note that due to [[scp|SCP protocol]] requirements WinSCP needs to know the size of converted text files before the transfer actually starts. For that reason with SCP protocol, the whole file is converted in memory before the transfer. | + | |
| - | + | ||
| - | If the file is too large (not common for text files), you can run out of memory during conversion. So to transfer large text file, either force binary mode (if possible) or switch to [[sftp|SFTP protocol]]. | + | |
| - | + | ||
| - | ===== Changing Transfer Mode ===== | + | |
| The transfer mode is set as part of [[transfer_settings|transfer settings]]. | The transfer mode is set as part of [[transfer_settings|transfer settings]]. | ||
| Note that there are two [[ui_toolbars#transfer|predefined transfer settings presets]], //Text// and //Binary// that may help you switching the mode. | Note that there are two [[ui_toolbars#transfer|predefined transfer settings presets]], //Text// and //Binary// that may help you switching the mode. | ||
| - | Transfer mode configured in default transfer settings may be overriden with text mode when [[ui_editor_preferences#external|transferring file to/from editor]]. | + | Transfer mode configured in default transfer settings may be overridden with text mode when [[ui_editor_preferences#external|transferring file to/from editor]]. |
| + | |||
| + | To configure transfer mode in [[scripting]], use ''-transfer'' switch of file transfer commands. In .NET assembly use ''[[library_transferoptions#transfermode|TransferOptions.TransferMode]]''. | ||
| + | |||
| + | ===== [[additional_modifications]] Additional Modifications ===== | ||
| + | WinSCP can perform additional modifications to the text files during transfer, if configured so. Particularly, it can remove UTF-8 byte order marks and eof-of-file marks from uploaded files with [[sftp|SFTP]] and [[scp|SCP]] protocols. See //[[ui_transfer_custom#upload|Remove BOM and EOF marks]]// transfer settings. | ||
| + | |||
| + | ===== [[scp]] Transferring Large Text Files with SCP Protocol ===== | ||
| + | Note that due to [[scp|SCP protocol]] requirements WinSCP needs to know the size of converted text files before the transfer actually starts. For that reason with SCP protocol, the whole file is converted in memory before the transfer. | ||
| + | |||
| + | If the file is too large (not common for text files), you can run out of memory during conversion. So to transfer large text file, either force binary mode (if possible) or switch to [[sftp|SFTP protocol]]. | ||
| - | To configure transfer mode in [[scripting]], use ''-transfer'' switch of file transfer commands. In .NET assembly use ''[[library_transferoptions|TransferOptions.TransferMode]]''. | + | ===== Debugging Transfer Mode ===== |
| - | ===== Additional Modifications ===== | + | See [[faq_line_breaks|*]] |
| - | WinSCP can perform additional modifications to the text files during transfer, if configured so. Particularly, it can remove UTF-8 byte-order masks and eof-of-file marks from uploaded files with [[sftp|SFTP]] and [[scp|SCP]] protocols. See //[[ui_transfer_custom#upload_options|Remove BOM and EOF marks]]// transfer settings. | + | |