<style type="text/css"> .sized { width: 3em; } </style> </head> <body> <h1>FileOpen() <span class="ver">[AHK_L 42+]</span></h1> <p>Opens a file to read specific content from it and/or to write new content into it.</p> <pre class="Syntax">file := <span class="func">FileOpen</span>(Filename, Flags <span class="optional">, Encoding</span>)</pre> <h2 id="Parameters">Parâmetros</h2> <dl> <dt>Filename</dt> <dd> <p>The path of the file to open, which is assumed to be in <a href="../Variables.htm#WorkingDir">A_WorkingDir</a> if an absolute path isn't specified.</p> <p><span class="ver">[v1.1.17+]:</span> Specify an asterisk (or two) as shown below to open the standard input/output/error stream:</p> <pre> FileOpen("*", "r") <em>; for stdin</em> FileOpen("*", "w") <em>; for stdout</em> FileOpen("**", "w") <em>; for stderr</em></pre> </dd> <dt>Flags</dt> <dd><p>Either <span class="ver">[in AHK_L 54+]</span> a string of characters indicating the desired access mode followed by other options (with optional spaces or tabs in between); or <span class="ver">[in AHK_L 42+]</span> a combination (sum) of numeric flags. Supported values are described in the tables below.</p></dd> <dt>Encoding</dt> <dd><p>The code page to use for text I/O if the file does not contain a UTF-8 or UTF-16 <a href="https://en.wikipedia.org/wiki/Byte_order_mark">byte order mark</a>, or if the <code>h</code> (handle) flag is used. If omitted, the current value of <a href="../Variables.htm#FileEncoding">A_FileEncoding</a> is used.</p></dd> </dl> <h2 id="Flags">Flags</h2> <h3 id="Access_modes">Access modes (mutually-exclusive)</h3> <table class="info"> <tr> <th class="sized center">Flag</th> <th class="sized right">Dec</th> <th class="sized right">Hex</th> <th abbr="Descr">Descrição</th> </tr> <tr> <td class="center">r</td> <td class="right">0</td> <td class="right">0x0</td> <td><i>Read:</i> Fails if the file doesn't exist.</td> </tr> <tr> <td class="center">w</td> <td class="right">1</td> <td class="right">0x1</td> <td><i>Write:</i> Creates a new file, <b style="color:red">overwriting any existing file</b>.</td> </tr> <tr> <td class="center">a</td> <td class="right">2</td> <td class="right">0x2</td> <td><i>Append:</i> Creates a new file if the file didn't exist, otherwise moves the file pointer to the end of the file.</td> </tr> <tr> <td class="center">rw</td> <td class="right">3</td> <td class="right">0x3</td> <td><i>Read/Write:</i> Creates a new file if the file didn't exist.</td> </tr> <tr> <td class="center">h</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>Indicates that <i>Filename</i> is a file handle to wrap in an object. Sharing mode flags are ignored and the file or stream represented by the handle is not checked for a byte order mark. The file handle is <b>not</b> closed automatically when the file object is destroyed and calling <a href="../objects/File.htm#Close">Close</a> has no effect. Note that <a href="../objects/File.htm#Seek">Seek</a>, <a href="../objects/File.htm#Tell">Tell</a> and <a href="../objects/File.htm#Length">Length</a> should not be used if <i>Filename</i> is a handle to a nonseeking device such as a pipe or a communications device.</td> </tr> </table> <h3 id="Sharing_mode_flags">Sharing mode flags</h3> <table class="info"> <tr> <th class="sized center">Flag</th> <th class="sized right">Dec</th> <th class="sized right">Hex</th> <th abbr="Descr">Descrição</th> </tr> <tr> <td class="center">-rwd</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>Locks the file for read, write and/or delete access. Any combination of <code>r</code>, <code>w</code> and <code>d</code> may be used. Specifying <code>-</code> is the same as specifying <code>-rwd</code>. If omitted entirely, the default is to share all access.</td> </tr> <tr> <td>&nbsp;</td> <td class="right">0</td> <td class="right">0x0</td> <td>If <i>Flags</i> is numeric, the absence of sharing mode flags causes the file to be locked.</td> </tr> <tr> <td>&nbsp;</td> <td class="right">256</td> <td class="right">0x100</td> <td>Shares <i>read</i> access.</td> </tr> <tr> <td>&nbsp;</td> <td class="right">512</td> <td class="right">0x200</td> <td>Shares <i>write</i> access.</td> </tr> <tr> <td>&nbsp;</td> <td class="right">1024</td> <td class="right">0x400</td> <td>Shares <i>delete</i> access.</td> </tr> </table> <h3 id="EOL_options">End of line (EOL) options</h3> <table class="info"> <tr> <th class="sized center">Flag</th> <th class="sized right">Dec</th> <th class="sized right">Hex</th> <th abbr="Descr">Descrição</th> </tr> <tr> <td class="center">`n</td> <td class="right">4</td> <td class="right">0x4</td> <td>Replace <code>`r`n</code> with <code>`n</code> when reading and <code>`n</code> with <code>`r`n</code> when writing.</td> </tr> <tr> <td class="center">`r</td> <td class="right">8</td> <td class="right">0x8</td> <td>Replace standalone <code>`r</code> with <code>`n</code> when reading.</td> </tr> </table> <h2 id="Return_Value">Return Value</h2> <p>If the file is opened successfully, the return value is a <a href="../objects/File.htm">File object</a>.</p> <p>If the function fails, the return value is 0 and <span class="ver">[in AHK_L 54+]</span> <a href="../Variables.htm#LastError">A_LastError</a> contains an error code.</p> <p>Use <code>if file</code> or <code>IsObject(file)</code> to check if the function succeeded.</p> <h2 id="Remarks">Remarks</h2> <p>When a UTF-8 or UTF-16 file is created, a byte order mark is written to the file <b>unless</b> <i>Encoding</i> (or <a href="FileEncoding.htm">A_FileEncoding</a> if <i>Encoding</i> is omitted) contains <code>UTF-8-RAW</code> or <code>UTF-16-RAW</code>.</p> <p>When a file containing a UTF-8 or UTF-16 byte order mark (BOM) is opened with read access, the BOM is excluded from the output by positioning the file pointer after it. Therefore, <code>File.Position</code> may report 3 or 2 immediately after opening the file.</p> <h2 id="Related">Tópicos relacionados</h2> <p><a href="FileEncoding.htm">FileEncoding</a>, <a href="../objects/File.htm">File Object</a>, <a href="FileRead.htm">FileRead</a></p> <h2 id="Examples">Exemplos</h2> <div class="ex" id="writeread"> <p><a class="ex_number" href="#writeread"></a> Writes some text to a file then reads it back into memory (it provides the same functionality as <a href="DllCall.htm#file">this DllCall example</a>).</p> <pre>FileSelectFile, FileName, S16,, Create a new file: if (FileName = "") return file := FileOpen(FileName, "w") if !IsObject(file) { MsgBox Can't open "%FileName%" for writing. return } TestString := "This is a test string.`r`n" <em>; When writing a file this way, use `r`n rather than `n to start a new line.</em> file.Write(TestString) file.Close() <em>; Now that the file was written, read its contents back into memory.</em> file := FileOpen(FileName, "r-d") <em>; read the file ("r"), share all access except for delete ("-d")</em> if !IsObject(file) { MsgBox Can't open "%FileName%" for reading. return } CharsToRead := StrLen(TestString) TestString := file.Read(CharsToRead) file.Close() MsgBox The following string was read from the file: %TestString%</pre> </div> <div class="ex" id="ExReadLine"> <p><a class="ex_number" href="#ExReadLine"></a> Opens the script in read-only mode and read its first line.</p> <pre>file := FileOpen(A_ScriptFullPath, "r") MsgBox % file.ReadLine()</pre> </div> <div class="ex" id="ExStreams"> <p><a class="ex_number" href="#ExStreams"></a> Demonstrates the usage of the standard input/output streams.</p> <pre><em>; Open a console window for this demonstration:</em> DllCall("AllocConsole") <em>; Open the application's stdin/stdout streams in newline-translated mode.</em> stdin := FileOpen("*", "r `n") <em>; Requires <span class="ver">[v1.1.17+]</span></em> stdout := FileOpen("*", "w `n") <em>; For older versions: ; stdin := FileOpen(DllCall("GetStdHandle", "int", -10, "ptr"), "h `n") ; stdout := FileOpen(DllCall("GetStdHandle", "int", -11, "ptr"), "h `n")</em> stdout.Write("Enter your query.`n\&gt; ") stdout.Read(0) <em>; Flush the write buffer.</em> query := RTrim(stdin.ReadLine(), "`n") stdout.WriteLine("Your query was '" query "'. Have a nice day.") stdout.Read(0) <em>; Flush the write buffer.</em> Sleep 5000 </pre> </div> </body> </html>