From 4509dad45d3e040d8f556b8cd2443fc80aba229b Mon Sep 17 00:00:00 2001
From: irc-html <irc-html@php.net>
Date: Wed, 2 Jan 2002 19:14:25 +0000
Subject: [PATCH] added example, fixed crack_check funcdef

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@66723 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/crack.xml | 59 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 50 insertions(+), 9 deletions(-)

diff --git a/functions/crack.xml b/functions/crack.xml
index dc61aef59f..6c78fea866 100644
--- a/functions/crack.xml
+++ b/functions/crack.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
  <reference id="ref.crack">
   <title>Crack functions</title>
   <titleabbrev>Crack functions</titleabbrev>
@@ -15,13 +15,51 @@
     More information regarding CrackLib along with the library can be found at
     <ulink url="&url.crack;">&url.crack;</ulink>.
    </simpara>
+   <simpara>
+    Cracklib is useful in testing the 'strength' of a password that checks
+    length, use of upper and lower case and a check against the specified CrackLib
+    dictionary.  CrackLib will also give helpful diagnostic messages that will
+    help 'strengthen' the password.
+    </simpara>
+    <para>
+     This example shows how to open a CrackLib dictionary, test a given password,
+     retrieve any diagnostic messages, and close the dictionary.
+     <example>
+      <title>CrackLib example</title>
+       <programlisting role="php">
+<![CDATA[
+<?php
+// Open CrackLib Dictionary
+$dictionary = crack_opendict('/usr/local/lib/pw_dict')
+     or die('Unable to open CrackLib dictionary');
+
+// Perform password check
+$check = crack_check($dictionary, 'gx9A2s0x');
+
+// Retrieve messages
+$diag = crack_getlastmessage();
+echo $diag; // 'strong password'
+
+// Close dictionary
+crack_closedict($dictionary);
+?>
+]]>
+       </programlisting>
+     </example>
+    </para>
+    <note>
+     <para>
+      If <function>crack_check</function> returns &true;,
+      <function>crack_getlastmessage</function> will return 'strong password'.
+     </para>
+    </note>
   </partintro>
 
 
   <refentry id="function.crack-opendict">
    <refnamediv>
     <refname>crack_opendict</refname>
-    <refpurpose>Opens a new cracklib dictionary</refpurpose>
+    <refpurpose>Opens a new CrackLib dictionary</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -36,7 +74,7 @@
     </para>
      &warn.experimental.func;
     <para>
-     <function>crack_opendict</function> opens the specified cracklib 
+     <function>crack_opendict</function> opens the specified CrackLib 
      <parameter>dictionary</parameter> for use with
      <function>crack_check</function>.
     </para>
@@ -55,7 +93,7 @@
   <refentry id="function.crack-closedict">
    <refnamediv>
     <refname>crack_closedict</refname>
-    <refpurpose>Closes an open cracklib dictionary </refpurpose>
+    <refpurpose>Closes an open CrackLib dictionary </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -72,9 +110,9 @@
     </para>
      &warn.experimental.func;
     <para>
-     <function>crack_closedict</function> closes the dictionary that is
-     associated with the specified <parameter>link_identifier</parameter>.
-     If <parameter>link_identifier</parameter> is not specified, the current
+     <function>crack_closedict</function> closes the specified
+     <parameter>dictionary</parameter> identifier.  If
+     <parameter>dictionary</parameter> is not specified, the current
      dictionary is closed.
     </para>
    </refsect1>
@@ -83,19 +121,22 @@
   <refentry id="function.crack-check">
    <refnamediv>
     <refname>crack_check</refname>
-    <refpurpose>Performs an obscure check with the given password </refpurpose>
+    <refpurpose>Performs an obscure check with the given password</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>string <function>crack_check</function></funcdef>
+      <funcdef>bool <function>crack_check</function></funcdef>
       <paramdef>resource
        <parameter><optional>dictionary</optional></parameter>
       </paramdef>
       <paramdef>string <parameter>password</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
+    <para> 
+     Returns &true; if <parameter>password</parameter> is strong, or &false; otherwise.
+    </para>
      &warn.experimental.func;
     <para>
      <function>crack_check</function> performs an obscure check with the given