From dc12b3bc553a0b4c33c66c045f914a8ea94a61b9 Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Sat, 16 Aug 2003 21:42:13 +0000
Subject: [PATCH] adding examples proposed by vincent at php dot net most of
 them are from users notes

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@138029 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/filesystem/functions/fileatime.xml  | 21 +++++++-
 reference/filesystem/functions/filectime.xml  | 23 ++++++++-
 reference/filesystem/functions/filesize.xml   | 19 ++++++-
 reference/filesystem/functions/filetype.xml   | 19 ++++++-
 reference/filesystem/functions/flock.xml      | 25 +++++++++-
 reference/filesystem/functions/fpassthru.xml  | 26 +++++++++-
 reference/filesystem/functions/fseek.xml      | 28 +++++++++--
 reference/filesystem/functions/fstat.xml      | 49 ++++++++++++++++++-
 reference/filesystem/functions/ftell.xml      | 23 ++++++++-
 .../filesystem/functions/is-executable.xml    | 22 ++++++++-
 reference/filesystem/functions/link.xml       |  4 +-
 reference/filesystem/functions/linkinfo.xml   | 16 +++++-
 reference/filesystem/functions/readlink.xml   | 17 ++++++-
 13 files changed, 274 insertions(+), 18 deletions(-)

diff --git a/reference/filesystem/functions/fileatime.xml b/reference/filesystem/functions/fileatime.xml
index 61f909753b..6b39414ff0 100644
--- a/reference/filesystem/functions/fileatime.xml
+++ b/reference/filesystem/functions/fileatime.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.fileatime">
    <refnamediv>
@@ -31,6 +31,25 @@
     
     &note.no-remote;
 
+    <para>
+     <example>
+      <title><function>fileatime</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+// outputs e.g.  somefile.txt was last accessed: December 29 2002 22:16:23.
+
+$filename = 'somefile.txt';
+if (file_exists($filename)) {
+    echo "$filename was last accessed: " . date ("F d Y H:i:s.", fileatime($filename));
+}
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <simpara>
      See also <function>filemtime</function>,
      <function>fileinode</function>, and
diff --git a/reference/filesystem/functions/filectime.xml b/reference/filesystem/functions/filectime.xml
index de4bc17170..17cf3e1641 100644
--- a/reference/filesystem/functions/filectime.xml
+++ b/reference/filesystem/functions/filectime.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.filectime">
    <refnamediv>
@@ -33,7 +33,26 @@
     &note.clearstatcache;
     
     &note.no-remote;
-    
+
+    <para>
+     <example>
+      <title><function>fileatime</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+// outputs e.g.  somefile.txt was last changed: December 29 2002 22:16:23.
+
+$filename = 'somefile.txt';
+if (file_exists($filename)) {
+    echo "$filename was last changed: " . date ("F d Y H:i:s.", filectime($filename));
+}
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>    
     <simpara>
      See also <function>filemtime</function>
     </simpara>
diff --git a/reference/filesystem/functions/filesize.xml b/reference/filesystem/functions/filesize.xml
index 33b77f0276..ef8f066da4 100644
--- a/reference/filesystem/functions/filesize.xml
+++ b/reference/filesystem/functions/filesize.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.filesize">
    <refnamediv>
@@ -28,6 +28,23 @@
 
     &note.no-remote;
 
+    <para>
+     <example>
+      <title><function>filesize</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+// outputs e.g.  somefile.txt: 1024 bytes
+
+$filename = 'somefile.txt';
+echo $filename . ': ' . filesize($filename) . ' bytes';
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <simpara>
      See also <function>file_exists</function>
     </simpara>
diff --git a/reference/filesystem/functions/filetype.xml b/reference/filesystem/functions/filetype.xml
index 5d678de4b0..5051ce2bdd 100644
--- a/reference/filesystem/functions/filetype.xml
+++ b/reference/filesystem/functions/filetype.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.filetype">
    <refnamediv>
@@ -26,8 +26,23 @@
     
     &note.no-remote;
 
+    <para>
+     <example>
+      <title><function>filetype</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+echo filetype('/etc/passwd');  // file
+echo filetype('/etc/');        // dir
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <simpara>
-     See also: <function>is_dir</function>, <function>is_file</function>, 
+     See also <function>is_dir</function>, <function>is_file</function>, 
      <function>is_link</function>, <function>file_exists</function>,
      <function>stat</function>, and <function>mime_content_type</function>.
     </simpara>
diff --git a/reference/filesystem/functions/flock.xml b/reference/filesystem/functions/flock.xml
index 5f3ec2dbee..7def091c3c 100644
--- a/reference/filesystem/functions/flock.xml
+++ b/reference/filesystem/functions/flock.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.flock">
    <refnamediv>
@@ -67,6 +67,29 @@
     <simpara>
       &return.success;
     </simpara>
+    <para>
+     <example>
+      <title><function>flock</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+$fp = fopen("/tmp/lock.txt", "w+");
+
+if (flock($fp, LOCK_EX)) { // do an exclusive lock
+    fwrite($fp, "Write something here\n");
+    flock($fp, LOCK_UN); // release the lock
+} else {
+    echo "Couldn't lock the file !";
+}
+
+fclose($fp);
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <note>
      <para>
       Because <function>flock</function> requires a file pointer, you may have
diff --git a/reference/filesystem/functions/fpassthru.xml b/reference/filesystem/functions/fpassthru.xml
index d8b3eb5259..82db7077f3 100644
--- a/reference/filesystem/functions/fpassthru.xml
+++ b/reference/filesystem/functions/fpassthru.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.fpassthru">
    <refnamediv>
@@ -50,6 +50,30 @@
       your scripts will be more portable.
      </para>
     </note>
+    <para>
+    <example>
+     <title>Using <function>fpassthru</function> with binary files</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+
+// open the file in a binary mode
+$name = ".\public\dev\img\ok.png";
+$fp = fopen($name, 'rb');
+
+// send the right headers
+header("Content-Type: image/png");
+header("Content-Length: ".filesize($name));
+
+// dump the picture and stop the script
+fpassthru($fp);
+exit;
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <simpara>
      See also <function>readfile</function>,
      <function>fopen</function>, <function>popen</function>, and
diff --git a/reference/filesystem/functions/fseek.xml b/reference/filesystem/functions/fseek.xml
index 402fff4a33..dbc9f32feb 100644
--- a/reference/filesystem/functions/fseek.xml
+++ b/reference/filesystem/functions/fseek.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.fseek">
    <refnamediv>
@@ -29,13 +29,35 @@
       value in <parameter>offset</parameter>.)</member>
      </simplelist>
     </para>
-    <para>If <parameter>whence</parameter> is not specified, it is assumed to be
-    <constant>SEEK_SET</constant>.
+    <para>
+     If <parameter>whence</parameter> is not specified, it is assumed to be
+     <constant>SEEK_SET</constant>.
     </para>
     <para>
      Upon success, returns 0; otherwise, returns -1. Note that seeking
      past EOF is not considered an error.
     </para>
+    <para>
+     <example>
+      <title><function>fseek</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+$fp = fopen('somefile.txt');
+
+// read some data
+$data = fgets($fp, 4096);
+
+// move back to the begining of the file
+// same as rewind($fp);
+fseek($fp, 0);
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      May not be used on file pointers returned by
      <function>fopen</function> if they use the "http://" or "ftp://"
diff --git a/reference/filesystem/functions/fstat.xml b/reference/filesystem/functions/fstat.xml
index a2add81a7d..8f8b7eaa51 100644
--- a/reference/filesystem/functions/fstat.xml
+++ b/reference/filesystem/functions/fstat.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.24 -->
   <refentry id="function.fstat">
    <refnamediv>
@@ -22,6 +22,53 @@
      Returns an array with the statistics of the file; the format of the array
      is described in detail on the <function>stat</function> manual page.
     </para>
+    <para>
+     <example>
+      <title><function>fstat</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+// open a file
+$fp = fopen("/etc/passwd", "r");
+
+// gather statistics
+$fstat = fstat($fp);
+
+// close the file
+fclose($fp);
+
+// print only the associative part
+print_r(array_slice($fstat, 13));
+
+?>
+]]>
+      </programlisting>
+      <para>
+       this will output :
+      </para>
+      <screen>
+<![CDATA[
+Array
+(
+    [dev] => 771
+    [ino] => 488704
+    [mode] => 33188
+    [nlink] => 1
+    [uid] => 0
+    [gid] => 0
+    [rdev] => 0
+    [size] => 1114
+    [atime] => 1061067181
+    [mtime] => 1056136526
+    [ctime] => 1056136526
+    [blksize] => 4096
+    [blocks] => 8
+)
+]]>
+      </screen>
+     </example>
+    </para>
     
     &note.clearstatcache;
     
diff --git a/reference/filesystem/functions/ftell.xml b/reference/filesystem/functions/ftell.xml
index 8c72dbe2a8..0b1b701076 100644
--- a/reference/filesystem/functions/ftell.xml
+++ b/reference/filesystem/functions/ftell.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.ftell">
    <refnamediv>
@@ -25,6 +25,27 @@
      successfully opened by <function>fopen</function> or
      <function>popen</function>.
     </para>
+    <para>
+     <example>
+      <title><function>ftell</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+// opens a file and read some data
+$fp = fopen("/etc/passwd", "r");
+$data = fgets($fp, 12);
+
+// where are we ?
+echo ftell($fp); // 11
+
+fclose($fp);
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para> 
      See also <function>fopen</function>, <function>popen</function>,
      <function>fseek</function>, and <function>rewind</function>.
diff --git a/reference/filesystem/functions/is-executable.xml b/reference/filesystem/functions/is-executable.xml
index 79d7e435ba..689b547076 100644
--- a/reference/filesystem/functions/is-executable.xml
+++ b/reference/filesystem/functions/is-executable.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.is-executable">
    <refnamediv>
@@ -19,6 +19,26 @@
      <function>is_executable</function> became available with Windows in PHP
      version 5.0.0.
     </para>
+    <para>
+     <example>
+      <title><function>is_executable</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+$file = '/home/vincent/somefile.sh';
+
+if(is_executable($file)) {
+    echo $file.' is executable';
+} else {
+    echo $file.' is not executable';
+}
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     
     &note.clearstatcache;
 
diff --git a/reference/filesystem/functions/link.xml b/reference/filesystem/functions/link.xml
index ea7fbaa205..dac1f64a4c 100644
--- a/reference/filesystem/functions/link.xml
+++ b/reference/filesystem/functions/link.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.link">
    <refnamediv>
@@ -14,7 +14,7 @@
       <methodparam><type>string</type><parameter>link</parameter></methodparam>
      </methodsynopsis>
     <para>
-     <function>link</function> creates a hard link.
+     <function>link</function> creates a hard link. &return.success;
     </para>
     
     &note.no-remote;
diff --git a/reference/filesystem/functions/linkinfo.xml b/reference/filesystem/functions/linkinfo.xml
index f8d69a6e0a..ab690885cf 100644
--- a/reference/filesystem/functions/linkinfo.xml
+++ b/reference/filesystem/functions/linkinfo.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.linkinfo">
    <refnamediv>
@@ -20,6 +20,20 @@
      as the S_ISLNK macro defined in stat.h).  Returns 0 or &false; in
      case of error.
     </para>
+    <para>
+     <example>
+      <title><function>linkinfo</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+echo linkinfo('/vmlinuz'); // 835
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      See also <function>symlink</function>, <function>link</function>,
      and <function>readlink</function>.
diff --git a/reference/filesystem/functions/readlink.xml b/reference/filesystem/functions/readlink.xml
index e78f87b40b..d30e1e495b 100644
--- a/reference/filesystem/functions/readlink.xml
+++ b/reference/filesystem/functions/readlink.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.readlink">
    <refnamediv>
@@ -17,6 +17,21 @@
     function and returns the contents of the symbolic link path or 0
     in case of error.
     </para>
+   <para>
+    <example>
+     <title><function>readlink</function> example</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+
+// output e.g. /boot/vmlinux-2.4.20-xfs
+echo readlink('/vmlinuz');
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      See also <function>is_link</function>,
      <function>symlink</function>, and