home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / catman / p_man / cat3 / File::Copy.Z / File::Copy
Encoding:
Text File  |  1998-10-28  |  8.4 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      FFFFiiiilllleeee::::::::CCCCooooppppyyyy((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     FFFFiiiilllleeee::::::::CCCCooooppppyyyy((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       File::Copy - Copy files or filehandles
  10.  
  11.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.           use File::Copy;
  13.  
  14.           copy("file1","file2");
  15.           copy("Copy.pm",\*STDOUT);'
  16.           move("/dev1/fileA","/dev2/fileB");
  17.  
  18.           use POSIX;
  19.           use File::Copy cp;
  20.  
  21.           $n=FileHandle->new("/dev/null","r");
  22.           cp($n,"x");'
  23.  
  24.  
  25.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  26.       The File::Copy module    provides two basic functions, copy and
  27.       move,    which are useful for getting the contents of a file
  28.       from one place to another.
  29.  
  30.       +o   The copy function    takes two parameters: a    file to    copy
  31.           from and a file to copy to. Either argument may be a
  32.           string, a    FileHandle reference or    a FileHandle glob.
  33.           Obviously, if the    first argument is a filehandle of some
  34.           sort, it will be read from, and if it is a file _n_a_m_e it
  35.           will be opened for reading. Likewise, the    second
  36.           argument will be written to (and created if need be).
  37.  
  38.           NNNNooootttteeee tttthhhhaaaatttt    ppppaaaassssssssiiiinnnngggg    iiiinnnn ffffiiiilllleeeessss aaaassss hhhhaaaannnnddddlllleeeessss iiiinnnnsssstttteeeeaaaadddd ooooffff nnnnaaaammmmeeeessss
  39.           mmmmaaaayyyy lllleeeeaaaadddd ttttoooo lllloooossssssss ooooffff iiiinnnnffffoooorrrrmmmmaaaattttiiiioooonnnn oooonnnn ssssoooommmmeeee ooooppppeeeerrrraaaattttiiiinnnngggg
  40.           ssssyyyysssstttteeeemmmmssss;;;; iiiitttt iiiissss rrrreeeeccccoooommmmmmmmeeeennnnddddeeeedddd tttthhhhaaaatttt yyyyoooouuuu uuuusssseeee ffffiiiilllleeee nnnnaaaammmmeeeessss
  41.           wwwwhhhheeeennnneeeevvvveeeerrrr ppppoooossssssssiiiibbbblllleeee....  Files    are opened in binary mode
  42.           where applicable.     To get    a consistent behavour when
  43.           copying from a filehandle    to a file, use binmode on the
  44.           filehandle.
  45.  
  46.           An optional third    parameter can be used to specify the
  47.           buffer size used for copying. This is the    number of
  48.           bytes from the first file, that wil be held in memory at
  49.           any given    time, before being written to the second file.
  50.           The default buffer size depends upon the file, but will
  51.           generally    be the whole file (up to 2Mb), or 1k for
  52.           filehandles that do not reference    files (eg. sockets).
  53.  
  54.           You may use the syntax use File::Copy "cp" to get    at the
  55.           "cp" alias for this function. The    syntax is _e_x_a_c_t_l_y the
  56.           same.
  57.  
  58.       +o   The move function    also takes two parameters: the current
  59.           name and the intended name of the    file to    be moved.  If
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 10/23/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      FFFFiiiilllleeee::::::::CCCCooooppppyyyy((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     FFFFiiiilllleeee::::::::CCCCooooppppyyyy((((3333))))
  71.  
  72.  
  73.  
  74.           the destination already exists and is a directory, and
  75.           the source is not    a directory, then the source file will
  76.           be renamed into the directory specified by the
  77.           destination.
  78.  
  79.           If possible, _m_o_v_e() will simply rename the file.
  80.           Otherwise, it copies the file to the new location    and
  81.           deletes the original.  If    an error occurs    during this
  82.           copy-and-delete process, you may be left with a
  83.           (possibly    partial) copy of the file under    the
  84.           destination name.
  85.  
  86.           You may use the "mv" alias for this function in the same
  87.           way that you may use the "cp" alias for copy.
  88.  
  89.       File::Copy also provides the syscopy routine,    which copies
  90.       the file specified in    the first parameter to the file
  91.       specified in the second parameter, preserving    OS-specific
  92.       attributes and file structure.  For Unix systems, this is
  93.       equivalent to    the simple copy    routine.  For VMS systems,
  94.       this calls the rmscopy routine (see below).  For OS/2
  95.       systems, this    calls the syscopy XSUB directly.
  96.  
  97.       SSSSppppeeeecccciiiiaaaallll bbbbeeeehhhhaaaavvvviiiioooorrrr iiiiffff ssssyyyyssssccccooooppppyyyy is defined (VMS and OS/2)
  98.  
  99.       If both arguments to copy are    not file handles, then copy
  100.       will perform a "system copy" of the input file to a new
  101.       output file, in order    to preserve file attributes, indexed
  102.       file structure, _e_t_c.    The buffer size    parameter is ignored.
  103.       If either argument to    copy is    a handle to an opened file,
  104.       then data is copied using Perl operators, and    no effort is
  105.       made to preserve file    attributes or record structure.
  106.  
  107.       The system copy routine may also be called directly under
  108.       VMS and OS/2 as File::Copy::syscopy (or under    VMS as
  109.       File::Copy::rmscopy, which is    the routine that does the
  110.       actual work for syscopy).
  111.  
  112.       rmscopy($from,$to[,$date_flag])
  113.           The first    and second arguments may be strings,
  114.           typeglobs, typeglob references, or objects inheriting
  115.           from IO::Handle; they are    used in    all cases to obtain
  116.           the _f_i_l_e_s_p_e_c of the input    and output files,
  117.           respectively.  The name and type of the input file are
  118.           used as defaults for the output file, if necessary.
  119.  
  120.           A    new version of the output file is always created,
  121.           which inherits the structure and RMS attributes of the
  122.           input file, except for owner and protections (and
  123.           possibly timestamps; see below).    All data from the
  124.           input file is copied to the output file; if either of
  125.           the first    two parameters to rmscopy is a file handle,
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 10/23/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      FFFFiiiilllleeee::::::::CCCCooooppppyyyy((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     FFFFiiiilllleeee::::::::CCCCooooppppyyyy((((3333))))
  137.  
  138.  
  139.  
  140.           its position is unchanged.  (Note    that this means    a file
  141.           handle pointing to the output file will be associated
  142.           with an old version of that file after rmscopy returns,
  143.           not the newly created version.)
  144.  
  145.           The third    parameter is an    integer    flag, which tells
  146.           rmscopy how to handle timestamps.     If it is < 0, none of
  147.           the input    file's timestamps are propagated to the    output
  148.           file.  If    it is >    0, then    it is interpreted as a
  149.           bitmask: if bit 0    (the LSB) is set, then timestamps
  150.           other than the revision date are propagated; if bit 1 is
  151.           set, the revision    date is    propagated.  If    the third
  152.           parameter    to rmscopy is 0, then it behaves much like the
  153.           DCL COPY command:     if the    name or    type of    the output
  154.           file was explicitly specified, then no timestamps    are
  155.           propagated, but if they were taken implicitly from the
  156.           input filespec, then all timestamps other    than the
  157.           revision date are    propagated.  If    this parameter is not
  158.           supplied,    it defaults to 0.
  159.  
  160.           Like copy, rmscopy returns 1 on success.    If an error
  161.           occurs, it sets $!, deletes the output file, and returns
  162.           0.
  163.  
  164.      RRRREEEETTTTUUUURRRRNNNN
  165.       All functions    return 1 on success, 0 on failure.  $! will be
  166.       set if an error was encountered.
  167.  
  168.      AAAAUUUUTTTTHHHHOOOORRRR
  169.       File::Copy was written by Aaron Sherman <_a_j_s@_a_j_s._c_o_m>    in
  170.       1995,    and updated by Charles Bailey
  171.       <_b_a_i_l_e_y@_g_e_n_e_t_i_c_s._u_p_e_n_n._e_d_u> in 1996.
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 10/23/98)
  196.  
  197.  
  198.  
  199.