<doc>
	<legacy_id>1988</legacy_id>
	<name>write to file</name>
	<type>command</type>

	<syntax>
		<example>write <i>value</i> to {file <i>pathName</i> | stdout} [at {<i>start</i> | EOF | end}]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Places data in a <keyword tag="file">file</keyword> that has been opened with the <command tag="open file">open file</command> <glossary tag="command">command</glossary>.</summary>

	<examples>
<example>write "test" to file "test.txt"</example>
<example>write linefeed to stdout</example>
<example><p>write "Hello" &amp; return to stdout</p></example>
<example>write "ATZ" to file "modem:"</example>
<example><p>mouseUp</p><p>   local tFile</p><p>   put specialFolderPath("desktop")  &amp; "/test.txt" into tFile</p><p>   open file tFile for text </p><p></p><p>   write "one 222" to file tFile -- Writes to the start of the file</p><p>   write "two" to file tFile at 4 -- Writes to the file from character 4</p><p>   write " three" to file tFile at EOF -- Writes to the end of the file</p><p>   write " four" to file tFile at end -- Writes to the end of the file</p><p>   </p><p>   close file tFile</p><p>mouseUp</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
		<disk/>
	</security>


	<classification>
		<category>Files, Folders, &amp; Resources</category>
	</classification>

	<references>
		<command tag="write to driver">write to driver Command</command>
		<command tag="close file">close file Command</command>
		<keyword tag="stdout">stdout Keyword</keyword>
	</references>

	<description>Use the <b>write to file</b> <glossary tag="command">command</glossary> to change the contents of a <keyword tag="file">file</keyword>.<p></p><p><b>Parameters:</b></p><p>The <i>value</i> is any <glossary tag="expression">expression</glossary> that <glossary tag="evaluate">evaluates</glossary> to a <keyword tag="string">string</keyword>.</p><p></p><p>The <i>pathName</i> specifies the <glossary tag="file path">name and location</glossary> of the <keyword tag="file">file</keyword> you want to write to. It must be the same as the <glossary tag="file path">path</glossary> you used with the <command tag="open file">open file</command> command. The <i>pathName</i> is case-sensitive, even on <glossary tag="platform">platforms</glossary> where <keyword tag="file">file</keyword> names are not case-sensitive.</p><p></p><p>If you specify the name of a serial port on Mac OS or Windows systems, LiveCode writes to the specified port. The names of serial ports end in a colon (:).</p><p></p><p>The <i>start</i> specifies the <keyword tag="character">character</keyword> or <glossary tag="byte">byte</glossary> position in the <keyword tag="file">file</keyword> where you want to begin writing. A positive number begins <i>start</i> <keyword tag="characters">characters</keyword> after the beginning of the <keyword tag="file">file</keyword>; a <glossary tag="negative">negative</glossary> number begins <i>start</i> <keyword tag="characters">characters</keyword> before the end of the <keyword tag="file">file</keyword>.</p><p></p><p>If you specify either of the synonyms <constant tag="EOF">EOF</constant> or <keyword tag="end">end</keyword>, the write begins after the last character in the file.</p><p></p><p>If you don't specify a <i>start</i>, the write begins:</p><p></p><p>* at the position determined by the <command tag="seek">seek command</command>, or </p><p></p><p>* if you haven't used the <command tag="seek">seek command</command>, wherever the last <command tag="read from file">read from file</command> or <b>write to file</b> <glossary tag="command">command</glossary> to the <keyword tag="file">file</keyword> left off, or</p><p></p><p>* if you haven't accessed the file with <command tag="read from file">read from file</command> or <b>write to file</b> since it was opened, after the last character (if the <keyword tag="file">file</keyword> was opened in append mode) or at the first character (if the <keyword tag="file">file</keyword> was opened in any other mode).</p><p></p><p><b>Comments:</b></p><p>The file to write to must be opened first with the <command tag="open file">open file command</command>, and the mode the <keyword tag="file">file</keyword> was opened in must be write, append, or update. If the file is not open or is open read-only, the <function tag="result">result</function> function is set to "File is not open for write.".</p><p></p><p>If the file was opened in write mode, the <b>write to file</b> <glossary tag="command">command</glossary> completely replaces the file contents from the <i>start</i>. For example, if the <keyword tag="file">file</keyword> originally contains "ABC", and you write "1" to it, after the <b>write to file</b> <glossary tag="command">command</glossary> is <glossary tag="execute">executed</glossary> the file contains "1".</p><p></p><p>If the file was opened in update mode, if you write less data to the file than it already contains, the <b>write to file</b> <glossary tag="command">command</glossary> does not remove <keyword tag="characters">characters</keyword> from it. For example, if the <keyword tag="file">file</keyword> originally contains "ABC", and you write "1" to it, after the <b>write to file</b> <glossary tag="command">command</glossary> is <glossary tag="execute">executed</glossary> the file contains "1BC".</p><p></p><p>If the file was opened in append mode, the write begins at the end of the file.</p><p></p><p></p><p></p><important>After writing, you must close the file with the <command tag="close file">close filecommand</command>.</important><p></p><p>The write to stdout form writes to the standard output (on Unix systems). The standard output is always open, so you can write to it without first opening it.</p><p></p><p></p><p></p><tip>As an alternative to the <command tag="open file">open file</command> and <b>write to file</b> <glossary tag="command">commands</glossary>, you can also use the <keyword tag="URL">URLkeyword</keyword> with the <command tag="put">putcommand</command> to change the contents of a <keyword tag="file">file</keyword>.</tip></description>
</doc>