Differences
This shows you the differences between the selected revisions of the page.
| transfer_mode 2005-03-18 | 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 transfered, but also converted to format used by the target platform. The mode must not be used for binary files (inluding document files from modern text processors, like Microsoft Word), as they must be transfered 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 ===== | ||
| - | For the reason, WinSCP offers you chance to select between //Text// and //Binary// transfer modes. You can set the default transfer mode on //[[ui_pref_transfer|Transfer tab]]// of Preference dialog or change the mode for particular transfer only on [[ui_copy|Upload/Download dialog]]. | + | WinSCP offers you the chance to select between //Text// and //Binary// transfer modes. It is set as one of the [[transfer_settings|transfer settings]]. |
| - | WinSCP has also special //Automatic// mode (default). With the mode WinSCP decides automatically about transfer mode for particular file based on its filename (usually extension part). The so-called text file mask can be configured in dialogs mentioned above. By default it includes HTML, TXT, PHP, XML, INI, C, CPP and other file types. You can modify the mask as you need. | + | WinSCP also has a special //Automatic// mode (default). With this mode WinSCP decides automatically about transfer mode for a particular file based on its filename (usually the file extension). The so-called text file mask can be configured in dialogs mentioned above. By default it includes %%HTML, TXT, PHP, XML, INI, C, CPP%% and other file types. You can modify the mask as you need. |
| - | Files not matching the mask are transfered 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) knowns 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 [[protocols|SFTP protocol version 4 and newer]]. | + | 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 [[protocols|SCP protocol and SFTP protocol below version 4]]. It this case the client (WinSCP) must directly know and support the server-side format. Generally there is plenty of text file formats, almost every platform has it own format. WinSCP supports two most used formats, Unix and Windows. You can select between them on //[[ui_login_environment#server_eol_characters|Environment tab]]// 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]]. |
| + | |||
| + | ===== [[changing]] Changing Transfer Mode ===== | ||
| + | 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. | ||
| + | |||
| + | 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]]. | ||
| + | |||
| + | ===== Debugging Transfer Mode ===== | ||
| - | ===== Transferring Large Text Files with SCP Protocol ===== | + | See [[faq_line_breaks|*]] |
| - | Note that due to [[protocols|SCP protocol]] requirements WinSCP needs to know size of converted test file before the transfer actually starts. For the 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 [[protocols|SFTP protocol]]. | ||