git.maemo.org Git - dh-make-perl/blob - dev/arm/libio-stringy-perl/io-stringy-2.110/docs/IO/AtomicFile.pm.html

   1 <HTML>
   2 <HEAD>
   3   <TITLE>IO::AtomicFile 2.101</TITLE>
   4 </HEAD>
   5 <BODY
   6        bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666">
   7 <FONT FACE="sans-serif" SIZE=-1><A HREF="http://www.zeegee.com" TARGET="_top"><IMG SRC="icons/zeegee.gif" ALT="ZeeGee Software" ALIGN="RIGHT" BORDER="0"></A><A NAME="__TOP__"><H1>IO::AtomicFile 2.101</H1>
   8 </A><UL>
   9 <LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A>
  10 <LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A>
  11 <LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A>
  12 <LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A>
  13 <LI> <A NAME="menu:REVISION"><A HREF="#REVISION">REVISION</A></A>
  14 </UL>
  15
  16
  17 <P><HR>
  18 <A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A>
  19
  20
  21 <P>IO::AtomicFile - write a file which is updated atomically
  22
  23
  24
  25 <P><HR>
  26 <A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A>
  27
  28 <FONT SIZE=3 FACE="courier"><PRE>
  29     use IO::AtomicFile;
  30 </PRE></FONT>
  31 <FONT SIZE=3 FACE="courier"><PRE>
  32     ### Write a temp file, and have it install itself when closed:
  33     my $FH = IO::AtomicFile-&gt;open(&quot;bar.dat&quot;, &quot;w&quot;);
  34     print $FH &quot;Hello!\n&quot;;
  35     $FH-&gt;close || die &quot;couldn't install atomic file: $!&quot;;
  36 </PRE></FONT>
  37 <FONT SIZE=3 FACE="courier"><PRE>
  38     ### Write a temp file, but delete it before it gets installed:
  39     my $FH = IO::AtomicFile-&gt;open(&quot;bar.dat&quot;, &quot;w&quot;);
  40     print $FH &quot;Hello!\n&quot;;
  41     $FH-&gt;delete;
  42 </PRE></FONT>
  43 <FONT SIZE=3 FACE="courier"><PRE>
  44     ### Write a temp file, but neither install it nor delete it:
  45     my $FH = IO::AtomicFile-&gt;open(&quot;bar.dat&quot;, &quot;w&quot;);
  46     print $FH &quot;Hello!\n&quot;;
  47     $FH-&gt;detach;
  48 </PRE></FONT>
  49
  50
  51 <P><HR>
  52 <A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
  53
  54
  55 <P>This module is intended for people who need to update files
  56 reliably in the face of unexpected program termination.
  57
  58
  59 <P>For example, you generally don't want to be halfway in the middle of
  60 writing <I>/etc/passwd</I> and have your program terminate!  Even
  61 the act of writing a single scalar to a filehandle is <I>not</I> atomic.
  62
  63
  64 <P>But this module gives you true atomic updates, via rename().
  65 When you open a file <I>/foo/bar.dat</I> via this module, you are <I>actually</I>
  66 opening a temporary file <I>/foo/bar.dat..TMP</I>, and writing your
  67 output there.   The act of closing this file (either explicitly
  68 via close(), or implicitly via the destruction of the object)
  69 will cause rename() to be called... therefore, from the point
  70 of view of the outside world, the file's contents are updated
  71 in a single time quantum.
  72
  73
  74 <P>To ensure that problems do not go undetected, the &quot;close&quot; method
  75 done by the destructor will raise a fatal exception if the rename()
  76 fails.  The explicit close() just returns undef.
  77
  78
  79 <P>You can also decide at any point to trash the file you've been
  80 building.
  81
  82
  83
  84 <P><HR>
  85 <A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A>
  86
  87
  88 <P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>).
  89 President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>).
  90
  91
  92
  93 <P><HR>
  94 <A NAME="REVISION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> REVISION</H2></A>
  95
  96
  97 <P>$Revision: 2.101 $
  98
  99 <P><HR>
 100 <ADDRESS><FONT SIZE=-1>
 101 Generated Sun Dec 21 13:54:37 2003 by cvu_pod2html
 102 </FONT></ADDRESS>
 103 </FONT></BODY>
 104 </HTML>