<doc>
	<legacy_id>2180</legacy_id>
	<name>open file</name>
	<type>command</type>

	<syntax>
		<example>open file <i>filePath</i> [for [ [<i>encoding</i>] text | binary] {update | read | write | append}]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Opens a <keyword tag="file">file</keyword> so its contents can be accessed or modified.</summary>

	<examples>
<example>open file "temp.txt"</example>
<example>open file "/etc/Glossary" for write</example>
<example><p>open file (myFilePath  "/"  myFileName) for binary read</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="7.0">Added encoding when opening</changed>
<changed version="4.6.1">Added Support for iOS.</changed>
		<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,  Resources</category>
	</classification>

	<references>
		<function tag="tempName">tempName Function</function>
		<command tag="answer file">answer file Command</command>
		<command tag="close file">close file Command</command>
		<property tag="umask">umask Property</property>
		<property tag="fileType">fileType Property</property>
	</references>

	<description>
	<overview>Use the <b>open file</b> <glossary tag="command">command</glossary> to create a <keyword tag="file">file</keyword> or prepare an existing <keyword tag="file">file</keyword> for use by the <command tag="read from file">read from file</command> or <command tag="write to file">write to file</command> <glossary tag="command">commands</glossary>.</overview>

		<parameters>
  <parameter>
    <name>filePath</name>
    <description>Specifies the name and location of the file you want to open or create. If you specify a name but not a location, LiveCode assumes the file is in the defaultFolder. If the file you specify doesn't exist, LiveCode creates it.</description>
  </parameter>		</parameters>

	<value></value>
	<comments>You can optionally specify either text or binary mode. If you specify text mode, when you use the <b>write to file</b> <glossary tag="command">command</glossary> to put data in the <keyword tag="file">file</keyword>, any line feed and return <keyword tag="characters">characters</keyword> are translated to the appropriate end-of-line marker for the current operating system before being written to the file. The end-of-line marker on <glossary tag="Mac OS">Mac OS</glossary> and <glossary tag="OS X">OS X systems</glossary> is a return character; on <glossary tag="Unix">Unix</glossary>, a line feed; on <function tag="openStacks">Windows</function>, a CRLF. When you use the <command tag="read from file">read from file</command> <glossary tag="command">command</glossary> to get data from the <keyword tag="file">file</keyword>, end-of-line markers are translated to the <constant tag="return">return</constant> <command tag="constant">constant</command>, and any <glossary tag="null">null characters</glossary> are translated to spaces (<glossary tag="ASCII">ASCII</glossary> 32). If you specify binary mode, null characters and end-of-line markers are not translated. If you do not specify a mode, the <keyword tag="file">file</keyword> is opened in text mode.<p></p><p>Use the for read form to open the file for reading. If the <keyword tag="file">file</keyword> is opened for reading, you can use the <command tag="read from file">read from file</command> <glossary tag="command">command</glossary> to examine its contents, but you cannot modify it. If you use the for read form and the file does not exist, LiveCode does not create it, and the <function tag="result">result</function> <control_st tag="function">function</control_st> <glossary tag="return">returns</glossary> "Can't open that file.". Use this form for files on CD-ROM and other read-only media.</p><p></p><p>Use the for write form to open the file for writing. If the file is opened for writing, the <b>write to file</b> <glossary tag="command">command</glossary> replaces the <glossary tag="file">file's</glossary> contents from the starting point to the end of the file. </p><p></p><p></p><p></p><p></p><p></p><important>: Before opening any file for writing, remember to back up the file contents as LiveCode will erase them even if you do not write to the file after opening it.</important><p></p><p>Use the for update form to open the file for both reading and writing. If the file is opened for update, you can use both the <b>read from file</b> and <command tag="write to file">write to file</command> <glossary tag="command">commands</glossary> to examine or change it, and writing to the file places the data at the specified position without replacing other characters beyond the written data.</p><p></p><p>Use the for append form to open the file for writing. If the file is opened for append, the <b>write to file</b> <glossary tag="command">command</glossary> adds its data to the end of the <keyword tag="file">file</keyword> without replacing its current contents.</p><p></p><p>If you do not specify a form, the file is opened for update.</p><p></p><p>On Mac OS and OS X systems, if the file does not already exist (so that the <b>open file</b> <glossary tag="command">command</glossary> creates it), the new <glossary tag="file">file's</glossary> <glossary tag="creator signature">creator signature</glossary> and <glossary tag="type signature">file type</glossary> are set to the values in the <property tag="fileType">fileType</property> <glossary tag="property">property</glossary>.</p><p></p><p>Any files you have opened are closed automatically when you quit the application.</p><p></p><p>You can use the <b>open file</b> <glossary tag="command">command</glossary> to open a serial <glossary tag="port">port</glossary> on <glossary tag="Mac OS">Mac OS</glossary> or <glossary tag="Windows">Windows systems</glossary>. On <glossary tag="Mac OS">Mac OS systems</glossary>, specify either "printer:" or "modem:". On Windows systems, specify either "COM1:", "COM2:", or up to "COM9:". Set the <b>serialControlString</b> <glossary tag="property">property</glossary> before opening the <glossary tag="port">port</glossary> to specify the baud rate and other settings.</p><p></p><p></p><p></p><p></p><p></p><note>On windows, it is imperative not to name a file with one of the reserved device names: CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8 and LPT9. Also do not use these names followed by an extension, for example, NUL.tx7.</note><p></p><p></p><p></p><p></p><p></p><note>If you specify the name of a serial port on Mac OS or Windows systems, LiveCode opens the specified port. The names of serial ports end in a colon (:).</note><p></p><p></p><p></p><p></p><p></p><tip>As an alternative to the <command tag="open file">open file</command>, <command tag="read from file">read from file</command>, and <command tag="write to file">write to file commands</command>, you can also use the <keyword tag="URL">URL keyword</keyword> with <command tag="get">get</command>, <command tag="put">put</command>, and other <glossary tag="command">commands</glossary> to access the contents of a <keyword tag="file">file</keyword>.</tip><p></p><p></p><p></p><p></p><p></p><note>iOS imposes strict controls over what you can and cannot access. Each application in iOS is stored in its own 'sandbox' folder (referred to as the home folder). An application is free to read and write files within this folder and its descendants, but it is not allowed to access anything outside of the 'sandbox'.</note><p></p><p></p><p></p><p></p><p></p><note>An Android application is installed on the phone in the form of its zip package. This means that any assets that are included are not available as discrete files in the native filesystem. In order to manage this the engine essentially 'virtualizes' the asset files you include, allowing (read-only) manipulation with all the standard LiveCode file and folder handling syntax.</note><p></p><p></p><p></p><p></p><change></change>From 7.0, it's possible to specify an encoding for the file being opened. By doing so, you can straight read or write to a file without having to call <function tag="textEncode">textEncode</function> or <function tag="textDecode">textDecode</function>; the encoding supported by open file are the same as these text encoding functions. If no encoding is provided, then <command tag="open file">open file</command> tries to read a Byte Order Mark exists at the beginning of the file. In success, the encoding is adapted and the BOM is ignored.</comments>
	</description>
</doc>