mingw/html/ext/NDBM_File/NDBM_File.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>NDBM_File - Tied access to ndbm files</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;NDBM_File - Tied access to ndbm files</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#diagnostics">DIAGNOSTICS</a></li>
  26         <ul>
  27
  28                 <li><a href="#ndbm_store_returned_1__errno_22__key_____at____"><code>ndbm store returned -1, errno 22, key &quot;...&quot; at ...</code></a></li>
  29         </ul>
  30
  31         <li><a href="#bugs_and_warnings">BUGS AND WARNINGS</a></li>
  32 </ul>
  33 <!-- INDEX END -->
  34
  35 <hr />
  36 <p>
  37 </p>
  38 <h1><a name="name">NAME</a></h1>
  39 <p>NDBM_File - Tied access to ndbm files</p>
  40 <p>
  41 </p>
  42 <hr />
  43 <h1><a name="synopsis">SYNOPSIS</a></h1>
  44 <pre>
  45   use Fcntl;   # For O_RDWR, O_CREAT, etc.
  46   use NDBM_File;</pre>
  47 <pre>
  48   tie(%h, 'NDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
  49     or die &quot;Couldn't tie NDBM file 'filename': $!; aborting&quot;;</pre>
  50 <pre>
  51   # Now read and change the hash
  52   $h{newkey} = newvalue;
  53   print $h{oldkey};
  54   ...</pre>
  55 <pre>
  56   untie %h;</pre>
  57 <p>
  58 </p>
  59 <hr />
  60 <h1><a name="description">DESCRIPTION</a></h1>
  61 <p><code>NDBM_File</code> establishes a connection between a Perl hash variable and
  62 a file in NDBM_File format;.  You can manipulate the data in the file
  63 just as if it were in a Perl hash, but when your program exits, the
  64 data will remain in the file, to be used the next time your program
  65 runs.</p>
  66 <p>Use <code>NDBM_File</code> with the Perl built-in <code>tie</code> function to establish
  67 the connection between the variable and the file.  The arguments to
  68 <code>tie</code> should be:</p>
  69 <ol>
  70 <li>
  71 <p>The hash variable you want to tie.</p>
  72 </li>
  73 <li>
  74 <p>The string <code>&quot;NDBM_File&quot;</code>.  (Ths tells Perl to use the <code>NDBM_File</code>
  75 package to perform the functions of the hash.)</p>
  76 </li>
  77 <li>
  78 <p>The name of the file you want to tie to the hash.</p>
  79 </li>
  80 <li>
  81 <p>Flags.  Use one of:</p>
  82 <dl>
  83 <dt><strong><a name="item_o_rdonly"><code>O_RDONLY</code></a></strong>
  84
  85 <dd>
  86 <p>Read-only access to the data in the file.</p>
  87 </dd>
  88 </li>
  89 <dt><strong><a name="item_o_wronly"><code>O_WRONLY</code></a></strong>
  90
  91 <dd>
  92 <p>Write-only access to the data in the file.</p>
  93 </dd>
  94 </li>
  95 <dt><strong><a name="item_o_rdwr"><code>O_RDWR</code></a></strong>
  96
  97 <dd>
  98 <p>Both read and write access.</p>
  99 </dd>
 100 </li>
 101 </dl>
 102 <p>If you want to create the file if it does not exist, add <code>O_CREAT</code> to
 103 any of these, as in the example.  If you omit <code>O_CREAT</code> and the file
 104 does not already exist, the <code>tie</code> call will fail.</p>
 105 <li>
 106 <p>The default permissions to use if a new file is created.  The actual
 107 permissions will be modified by the user's umask, so you should
 108 probably use 0666 here. (See <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_umask">umask in the perlfunc manpage</a>.)</p>
 109 </li>
 110 </ol>
 111 <p>
 112 </p>
 113 <hr />
 114 <h1><a name="diagnostics">DIAGNOSTICS</a></h1>
 115 <p>On failure, the <code>tie</code> call returns an undefined value and probably
 116 sets <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item___"><code>$!</code></a> to contain the reason the file could not be tied.</p>
 117 <p>
 118 </p>
 119 <h2><a name="ndbm_store_returned_1__errno_22__key_____at____"><code>ndbm store returned -1, errno 22, key &quot;...&quot; at ...</code></a></h2>
 120 <p>This warning is emitted when you try to store a key or a value that
 121 is too long.  It means that the change was not recorded in the
 122 database.  See BUGS AND WARNINGS below.</p>
 123 <p>
 124 </p>
 125 <hr />
 126 <h1><a name="bugs_and_warnings">BUGS AND WARNINGS</a></h1>
 127 <p>There are a number of limits on the size of the data that you can
 128 store in the NDBM file.  The most important is that the length of a
 129 key, plus the length of its associated value, may not exceed 1008
 130 bytes.</p>
 131 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#tie">tie in the perlfunc manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perldbmfilter.html">the perldbmfilter manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/Fcntl.html">the Fcntl manpage</a></p>
 132 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 133 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 134 <big><strong><span class="block">&nbsp;NDBM_File - Tied access to ndbm files</span></strong></big>
 135 </td></tr>
 136 </table>
 137
 138 </body>
 139
 140 </html>