<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Gets line from file pointer</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.fgetcsv.html">fgetcsv</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fgetss.html">fgetss</a></div>
<div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.fgets" class="refentry">
<div class="refnamediv">
<h1 class="refname">fgets</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">fgets</span> — <span class="dc-title">Gets line from file pointer</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.fgets-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">string</span> <span class="methodname"><strong>fgets</strong></span>
( <span class="methodparam"><span class="type">resource</span> <code class="parameter">$handle</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$length</code></span>
] )</div>
<p class="para rdfs-comment">
Gets a line from file pointer.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.fgets-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">handle</code></em></span>
<dd>
<p class="para">The file pointer must be valid, and must point to
a file successfully opened by <span class="function"><a href="function.fopen.html" class="function">fopen()</a></span> or
<span class="function"><a href="function.fsockopen.html" class="function">fsockopen()</a></span> (and not yet closed by
<span class="function"><a href="function.fclose.html" class="function">fclose()</a></span>).</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">length</code></em></span>
<dd>
<p class="para">
Reading ends when <em><code class="parameter">length</code></em> - 1 bytes have been
read, or a newline (which is included in the return value), or an EOF
(whichever comes first). If no length is specified, it will keep
reading from the stream until it reaches the end of the line.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Until PHP 4.3.0, omitting it would assume 1024 as the line length.
If the majority of the lines in the file are all larger than 8KB,
it is more resource efficient for your script to specify the maximum
line length.
</p>
</p></blockquote>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.fgets-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns a string of up to <em><code class="parameter">length</code></em> - 1 bytes read from
the file pointed to by <em><code class="parameter">handle</code></em>. If there is no more data
to read in the file pointer, then <strong><code>FALSE</code></strong> is returned.
</p>
<p class="para">
If an error occurs, <strong><code>FALSE</code></strong> is returned.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.fgets-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>4.3.0</td>
<td>
<span class="function"><strong>fgets()</strong></span> is now binary safe
</td>
</tr>
<tr>
<td>4.2.0</td>
<td>
The <em><code class="parameter">length</code></em> parameter became optional
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.fgets-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-2362">
<p><strong>Example #1 Reading a file line by line</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$handle </span><span style="color: #007700">= @</span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">"/tmp/inputfile.txt"</span><span style="color: #007700">, </span><span style="color: #DD0000">"r"</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$handle</span><span style="color: #007700">) {<br /> while ((</span><span style="color: #0000BB">$buffer </span><span style="color: #007700">= </span><span style="color: #0000BB">fgets</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">, </span><span style="color: #0000BB">4096</span><span style="color: #007700">)) !== </span><span style="color: #0000BB">false</span><span style="color: #007700">) {<br /> echo </span><span style="color: #0000BB">$buffer</span><span style="color: #007700">;<br /> }<br /> if (!</span><span style="color: #0000BB">feof</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">)) {<br /> echo </span><span style="color: #DD0000">"Error: unexpected fgets() fail\n"</span><span style="color: #007700">;<br /> }<br /> </span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">);<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.fgets-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>: <span class="simpara">If PHP is not properly recognizing
the line endings when reading files either on or created by a Macintosh
computer, enabling the
<a href="filesystem.configuration.html#ini.auto-detect-line-endings" class="link">auto_detect_line_endings</a>
run-time configuration option may help resolve the problem.</span></p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
People used to the 'C' semantics of <span class="function"><strong>fgets()</strong></span>
should note the difference in how <em>EOF</em> is returned.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.fgets-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.fgetss.html" class="function" rel="rdfs-seeAlso">fgetss()</a> - Gets line from file pointer and strip HTML tags</span></li>
<li class="member"> <span class="function"><a href="function.fread.html" class="function" rel="rdfs-seeAlso">fread()</a> - Binary-safe file read</span></li>
<li class="member"> <span class="function"><a href="function.fgetc.html" class="function" rel="rdfs-seeAlso">fgetc()</a> - Gets character from file pointer</span></li>
<li class="member"> <span class="function"><a href="function.stream-get-line.html" class="function" rel="rdfs-seeAlso">stream_get_line()</a> - Gets line from stream resource up to a given delimiter</span></li>
<li class="member"> <span class="function"><a href="function.fopen.html" class="function" rel="rdfs-seeAlso">fopen()</a> - Opens file or URL</span></li>
<li class="member"> <span class="function"><a href="function.popen.html" class="function" rel="rdfs-seeAlso">popen()</a> - Opens process file pointer</span></li>
<li class="member"> <span class="function"><a href="function.fsockopen.html" class="function" rel="rdfs-seeAlso">fsockopen()</a> - Open Internet or Unix domain socket connection</span></li>
<li class="member"> <span class="function"><a href="function.stream-set-timeout.html" class="function" rel="rdfs-seeAlso">stream_set_timeout()</a> - Set timeout period on a stream</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.fgetcsv.html">fgetcsv</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fgetss.html">fgetss</a></div>
<div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
