unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

filesync(1)                      User Commands                     filesync(1)



NAME
       filesync - synchronize ordinary, directory or special files

SYNOPSIS
       filesync  [-aehmnqvy]  [-o  src  |  dst]   [-f  src  | dst | old | new]
       [-r directory...]

       filesync [-aehmnqvy] -s source-dir -d dest-dir filename...

DESCRIPTION
       The filesync utility synchronizes files between multiple computer  sys-
       tems, typically a server and a portable computer. filesync synchronizes
       ordinary, directory or special files.  Although  intended  for  use  on
       nomadic  systems, filesync is useful for backup and file replication on
       more permanently connected systems.

       If files are synchronized between systems, the corresponding  files  on
       each  of  the  systems are identical. Changing a file on one or both of
       the systems causes the files to become different (not synchronized). In
       order  to  make  the files identical again, the differences between the
       files must be reconciled. See Reconciling and Synchronizing Files   for
       specific details about how filesync reconciles and synchronizes files.

       There are two forms of the filesync command. The first form of filesync
       is invoked without file arguments. This  form  of  filesync  reconciles
       differences between the files and systems specified in the $HOME/.pack-
       ingrules file. $HOME/.packingrules is a packing rules list for filesync
       and  cachefspack, and contains a list of files to be kept synchronized.
       See packingrules(4) and cachefspack(1M).

       The second form of filesync copies specific files from a  directory  on
       the  source  system  to a directory on the destination system. In addi-
       tion, this form of filesync adds the file or files specified  as  argu-
       ments  (filename) to $HOME/.packingrules. See -s and -d for information
       about specifying directories on source and destination systems. See OP-
       ERANDS for details about specifying file (filename) arguments.

       Multiple filesync commands are cumulative (that is, the specified files
       are added to the already existing packing rules file list). See  Multi-
       ple filesync Commands.

   Reconciling and Synchronizing Files
       filesync  synchronizes files between computer systems by performing the
       following two tasks:

       1.  filesync examines the directories and files specified in the  pack-
           ing  rules file on both systems, and determines whether or not they
           are identical. Any file that differs requires reconciliation.

           filesync also maintains a baseline summary in the  $HOME/.filesync-
           base  file for all of the files that are being monitored. This file
           lists the names, types, and sizes of all files as of the last  rec-
           onciliation.


       2.  Based  on  the  information  contained in the baseline file and the
           specified options (see   Resolving  filesync  Conflicts),  filesync
           determines  which  of  the  various  copies is the correct one, and
           makes the corresponding changes to the other system. Once this  has
           been done, the two copies are, again, identical (synchronized).

           If  a source file has changed and the destination file has not, the
           changes on the source system are propagated to the destination sys-
           tem. If a destination file has changed and the corresponding source
           file has not, the changes on the destination file are propagated to
           the  source system. If both systems have changed (and the files are
           not still identical) a warning message will be printed out,  asking
           the  user to resolve the conflict manually. See  Resolving filesync
           Conflicts.


   Resolving filesync Conflicts
       In cases where files on both sides have changed,  filesync attempts  to
       determine which version should be chosen. If  filesync cannot automati-
       cally determine which version should be selected, it prints out a warn-
       ing message and leaves the two incompatible versions of the file unrec-
       onciled.

       In these cases, you must either resolve the  differences  manually,  or
       tell   filesync how to choose which file should win. Use the  -o and -f
       options to tell  filesync how to resolve conflicts (see  OPTIONS).

       Alternatively, for each conflicting file, you can examine the two  ver-
       sions,  determine  which one should be kept, and manually bring the two
       versions into agreement (by copying, deleting, or changing  the  owner-
       ship or protection to be correct). You can then re-run  filesync to see
       whether or not any other conflicts remain.

   Packing Rules File
       The packing rules file $HOME/.packingrules contains a list of files  to
       be  kept  synchronized.  The  syntax of this file is described in pack-
       ingrules(4).

       The $HOME/.packingrules file is automatically created if  users  invoke
       filesync with filename arguments. By using filesync options, users
        can augment the packing rules in $HOME/.packingrules.

       Many users choose to create the packing rules file manually and edit it
       by hand. Users can edit $HOME/.packingrules (using any editor) to  per-
       manently  change  the   $HOME/.packingrules  file, or to gain access to
       more powerful options  that are not available  from  the  command  line
       (such as  IGNORE commands). It is much easier to enter complex wildcard
       expressions by editing the $HOME/.packingrules file.

   Baseline File
       $HOME/.filesync-base is the filesync baseline  summary  file.  filesync
       uses  the  information  in $HOME/.filesync-base to identify the differ-
       ences between  files  during  the  reconciliation  and  synchronization
       process.  Users  do not create or edit the baseline file. It is created
       automatically by filesync and records the last known state  of   agree-
       ment between all of the files being maintained.

   Multiple filesync Commands
       Over  a  period of time, the set of files you want to keep synchronized
       can change. It is common, for instance, to want to keep files  pertain-
       ing  to only a few active projects on your notebook. If you continue to
       keep files associated with every project you have ever worked  on  syn-
       chronized,  your  notebook's  disk  will  fill  up with old files. Each
       filesync command will waste a lot of time updating files you no  longer
       care about.

       If  you delete the files from your notebook, filesync will want to per-
       form the corresponding deletes on the server, which would not  be  what
       you  wanted. Rather, you would like a way to tell filesync to stop syn-
       chronizing some of the files. There are two ways to do this:

       1.  Edit  $HOME/.packingrules. Delete the rules for the files that  you
           want to delete.


       2.  Delete  $HOME/.packingrules.  Use  the  filesync command to specify
           the files that you want synchronized.


       Either way works, and you can choose the one that seems easiest to you.
       For  minor  changes,  it  is  probably easier to just edit $HOME/.pack-
       ingrules. For major  changes  it  is  probably  easier  to  start  from
       scratch.

       Once   filesync  is  no  longer  synchronizing  a set of files, you can
       delete them from your notebook without having any effect on the server.

   Nomadic Machines
       When using filesync to keep files synchronized between nomadic machines
       and a server, store the packing rules and baseline files on the nomadic
       machines, not the server. If, when logged into your notebook, the  HOME
       environment  variable  does  not  normally point to a directory on your
       notebook, you can use the FILESYNC environment variable to  specify  an
       alternate location for the packing rules and baseline files.

       Each  nomadic  machine  should carry its own packing rules and baseline
       file. Incorrect file synchronization can result if a server  carries  a
       baseline  file  and  multiple  nomadic  machines  attempt  to reconcile
       against the server's baseline file. In this  case,  a  nomadic  machine
       could  be  using  a baseline file that does not accurately describe the
       state of its files. This might result in incorrect reconciliations.

       To safeguard against the dangers associated  with  a  single   baseline
       file  being  shared by more than two machines,  filesync adds a default
       rule to each new packing rules file. This  default  rule  prevents  the
       packing rules and  baseline files from being copied.

OPTIONS
       The following options are supported:

       -a

           Force  the checking of Access Control Lists (ACLs )  and attempt to
           make them agree for all new and changed files. If it is not  possi-
           ble  to  set the ACL for a particular file, filesync stops ACL syn-
           chronization for that file.

           Some file systems do not support ACLs . It is not possible to  syn-
           chronize ACLs between file systems that support ACLs and those that
           do not; attempting to do so will result in numerous error messages.



       -d dest-dir

           Specify the directory on the destination system into which filename
           is  to  be copied.  Use with the -s source-dir option and the file-
           name operand. See -s and  OPERANDS.



       -e

           Flag all differences. It may not be possible to  resolve  all  con-
           flicts  involving modes and ownership (unless filesync is being run
           with root privileges). If you cannot change the ownership  or  pro-
           tections on a file, filesync will normally ignore conflicts in own-
           ership and protection. If  you  specify  the  -e  (everything  must
           agree) flag, however, filesync will flag these differences.



       -f src | dst | old | new

           The -f option tells filesync how to resolve conflicting changes. If
           a file has been changed on both systems, and an -f option has  been
           specified,  filesync  will  retain  the changes made on the favored
           system and discard the changes made on the unfavored system.

           Specify -f src to favor the  source-system file. Specify -f dst  to
           favor  the  destination-system  file.  Specify  -f old to favor the
           older version of the file. Specify -f new to favor the  newer  ver-
           sion of the file.

           It  is  possible  to specify the  -f and  -o options in combination
           if they both specify the same preference  (src and dst). If
            -f and  -o conflict, the  -f option is ignored. See the -o  option
           description.



       -h

           Halt  on  error.  Normally,  if filesync encounters a read or write
           error while copying files, it notes the error and the program  con-
           tinues, in an attempt to reconcile other files. If the -h option is
           specified, filesync will immediately halt when one of these  errors
           occurs and will not try to process any more files.



       -m

           Ensure  that  both  copies  of  the file have the same modification
           time. The modification time for newly copied files is  set  to  the
           time  of  reconciliation  by  default.  File changes are ordered by
           increasing modification times so that the propagated files have the
           same  relative  modification time ordering as the original changes.
           Users should be warned that there is usually some time skew between
           any  two systems, and transferring modification times from one sys-
           tem to another can occasionally produce strange results.

           There are instances in which using filesync to update some (but not
           all)  files  in a directory will confuse the  make program. If, for
           instance, filesync is keeping  .c files synchronized, but  ignoring
           .o  files,  a changed  .c file may show up with a modification time
           prior to a  .o file that was built from a prior version of the   .c
           file.



       -n

           Do  not  really  make  the changes. If the  -n option is specified,
           filesync determines what changes have been made to files, and  what
           reconciliations  are  required and displays this information on the
           standard output. No changes are made to files, including the  pack-
           ing rules file.

           Specifying  both  the  -n and -o options causes filesync to analyze
           the prevailing system and report the changes that have been made on
           that  system.   Using  -n  and  -o in combination is useful if your
           machine is disconnected (and you cannot access the server) but  you
           want  to know what changes have been made on the local machine. See
           the -o option description.



       -o src | dst

           The -o option forces a one-way reconciliation, favoring either  the
           source system (src) or destination system (dst).

           Specify  -o src to propagate changes only from the source system to
           the destination system. Changes made on the destination system  are
           ignored.  filesync  aborts if it cannot access a source or destina-
           tion directory.

           Specify -o dst to propagate changes only from the destination  sys-
           tem  to  the  source  system. Changes made on the source system are
           ignored. filesync aborts if it cannot access a source  or  destina-
           tion directory.

           Specifying  -n  with  the  -o option causes filesync to analyze the
           prevailing system and reports on what changes  have  been  made  on
           that  system. Using -n and -o in combination is useful if a machine
           is disconnected (and there is no access to  the  server),  but  you
           want  to know what changes have been made on the local machine. See
           the -n option description.

           It is possible to specify the -o and -f options in  combination  if
           they  both  specify  the same preference (src or dst). If -o and -f
           options conflict, the -f option will be ignored. See the -f  option
           description.



       -q

           Suppress  the  standard filesync messages that describe each recon-
           ciliation action as it is performed.

           The standard filesync message describes each reconciliation  action
           in  the  form of a UNIX shell command (for example, mv, ln, cp, rm,
           chmod, chown, chgrp, setfacl, and so forth).



       -r directory

           Limit the reconciliation to  directory. Specify  multiple  directo-
           ries with multiple -r specifications.



       -s source-dir

           Specify the directory on the source system from which the  filename
           to be copied is located. Use with the  -d dest-dir option  and  the
           filename operand. See the -d option description and  OPERANDS.



       -v

           Display  additional information about each file comparison as it is
           made on the standard output.



       -y

           Bypass safety check prompts.  Nomadic  machines  occasionally  move
           between  domains,  and many of the files on which filesync operates
           are expected to be accessed by NFS. There is a danger that  someday
           filesync will be asked to reconcile local changes against the wrong
           file system or server. This could result in a large number of inap-
           propriate copies and deletions. To prevent such a mishap,  filesync
           performs a few safety checks prior to reconciliation. If large num-
           bers  of files are likely to  be deleted, or if high level directo-
           ries have changed their I-node numbers,   filesync  prompts  for  a
           confirmation  before  reconciliation.  If  you  know  that  this is
           likely, and do not want to be prompted, use the -y (yes) option  to
           automatically confirm these prompts.



OPERANDS
       The following operands are supported:

       filename        The  name  of  the  ordinary  file, directory, symbolic
                       link, or special file in the specified source directory
                       (source-dir) to be synchronized. Specify multiple files
                       by separating each filename by spaces. Use the filename
                       operand with the -s and -d options. See  OPTIONS.

                       If  filename  is  an  ordinary file, that ordinary file
                       will be replicated (with  the  same  filename)  in  the
                       specified destination directory (dest-dir).

                       If  filename  is a directory, that directory and all of
                       the files and subdirectories under it  will  be  repli-
                       cated (recursively) in the specified destination direc-
                       tory (dest-dir).

                       If  filename is a symbolic link, a copy  of  that  sym-
                       bolic link will be replicated in the specified destina-
                       tion directory (dest-dir).

                       If filename is a special file, a special file with  the
                       same  major  or minor device numbers will be replicated
                       in the  specified  destination  directory.  (dest-dir).
                       Only  super-users  can  use  filesync to create special
                       files.

                       Files created in the destination  directory  (dest-dir)
                       will  have  the same owner, group and other permissions
                       as the files in the source directory.

                       If filename contains escaped shell wildcard characters,
                       the  wildcard  characters  are  stored  in $HOME/.pack-
                       ingrules and evaluated each time filesync is run.

                       For example, the following would make sure that the two
                       specified  files,  currently in $RHOME, were replicated
                       in  $HOME:

                       filesync -s $RHOME  -d $HOME a.c b.c



                       The following example would ensure that all of the  *.c
                       files  in   $RHOME  were  replicated in  $HOME, even if
                       those files were not created until later.

                       filesync -s $RHOME -d $HOME '*.c'



                       If  any  of  the  destination  files   already   exist,
                       filesync  ensures  that  they  are identical and issues
                       warnings if they are not.

                       Once files have been copied,  the  distinction  between
                       the  source  and  destination is a relatively arbitrary
                       one (except for its use in the -o and -f switches).



ENVIRONMENT VARIABLES
       FILESYNC                Specifies the default location of the  filesync
                               packing  rules  and baseline files. The default
                               value for this variable is $HOME. The  suffixes
                               .packingrules   and   .filesync-base   will  be
                               appended to form the names of the packing rules
                               and baseline files.



       LC_MESSAGES             Determines  how diagnostic and informative mes-
                               sages are presented. In  the  "C"  locale,  the
                               messages  are  presented  in  the  default form
                               found in the program  itself  (in  most  cases,
                               U.S. English).



EXIT STATUS
       Normally,  if  all  files  are already up-to-date, or if all files were
       successfully reconciled, filesync will exit with a status  of  0.  How-
       ever, if either the -n option was specified or any errors occurred, the
       exit status will be the logical OR of the following:

       0        No conflicts, all files up to date.



       1        Some resolvable conflicts.



       2        Some conflicts requiring manual resolution.



       4        Some specified files did not exist.



       8        Insufficient permission for some files.



       16       Errors accessing packing rules or baseline file.



       32       Invalid arguments.



       64       Unable to access either or both of the specified  src  or  dst
                directories.



       128      Miscellaneous other failures.



FILES
       $HOME/.packingrules             list of files to be kept synchronized



       $HOME/.filesync-base            baseline summary file



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE AvailabilitySUNWrcmdc


SEE ALSO
       cachefspack(1M), packingrules(4), attributes(5)



SunOS 5.10                        6 Nov 2000                       filesync(1)