cp-update.1

   1 .\" Copied from from Pod::Man template\r
   2 .\" Wed, 14 Mar 2006 21:15:00 +0100\r
   3 .\"\r
   4 .\" Standard preamble:\r
   5 .\" ======================================================================\r
   6 .de Sh \" Subsection heading\r
   7 .br\r
   8 .if t .Sp\r
   9 .ne 5\r
  10 .PP\r
  11 \fB\\$1\fR\r
  12 .PP\r
  13 ..\r
  14 .de Sp \" Vertical space (when we can't use .PP)\r
  15 .if t .sp .5v\r
  16 .if n .sp\r
  17 ..\r
  18 .de Ip \" List item\r
  19 .br\r
  20 .ie \\n(.$>=3 .ne \\$3\r
  21 .el .ne 3\r
  22 .IP "\\$1" \\$2\r
  23 ..\r
  24 .de Vb \" Begin verbatim text\r
  25 .ft CW\r
  26 .nf\r
  27 .ne \\$1\r
  28 ..\r
  29 .de Ve \" End verbatim text\r
  30 .ft R
  31
  32 .fi
  33 ..\r
  34 .\"\r
  35 .\" For nroff, turn off justification.  Always turn off hyphenation; it\r
  36 .\" makes way too many mistakes in technical documents.\r
  37 .hy 0\r
  38 .if n .na\r
  39 .\"
  40 .IX Title "cp-update 1"
  41 .TH cp-update 1 "March 2006" CARNet "CARNet Packaging Tools"
  42 .SH NAME\r
  43 cp-update \- versatile line-based file updating tool\r
  44 .\"
  45 .SH SYNOPSIS\r
  46 .B cp-update\r
  47 [\fIoptions\fR] \fIpackage\fR \fIfile\fR < \fIstdin-content\fR
  48 .\"
  49 .SH DESCRIPTION
  50 This tool is usually used in postinst scripts of CARNet "\-cn" packages\r
  51 to modify configuration files of other pre-installed packages. It eases\r
  52 task of manipulating portions of configuration files by tagging blocks\r
  53 of content with recognizable begin and end marks. Configuration block\r
  54 marked that way can later be easily updated or removed.\r
  55 .PP\r
  56 When making modifications to filesystem, \fBcp-update\fR tries to do it\r
  57 as atomically as possible, thus shortening the window when the system,\r
  58 or some particular package, can be left in an unusable state.\r
  59 .PP\r
  60 Default mode of execution is to add the block read from standard input\r
  61 to the configuration file, enclosed by begin and end marks, or replace\r
  62 existing block identified by \fIpackage\fR \- usually the package name.\r
  63 .PP\r
  64 The blocks added to configuration file using default options look like:\r
  65 .Sp\r
  66 .Vb 5\r
  67 \&  # Begin update by CARNet package test1 -- DO NOT DELETE THIS LINE!\r
  68 \&  Block inserted by test1,\r
  69 \&  using default options.\r
  70 \&  This is the third line.\r
  71 \&  # End update by CARNet package test1 -- DO NOT DELETE THIS LINE!\r
  72 .Ve
  73 .\"
  74 .SH OPTIONS
  75 Options provide a way to specify different operation mode, placement,\r
  76 block marking and file handling.\r
  77 .SS General options\r
  78 .Sp\r
  79 .TP
  80 \fB\-r\fR | \fB\-\-remove\fR\r
  81 Remove entry \fIpackage\fR from \fIfile\fR. Default is to add lines \r
  82 from stdin.\r
  83 .TP\r
  84 \fB\-x\fR | \fB\-\-change\fR\r
  85 Modify existing block, or add it if it does not exist but the begin \r
  86 mark can be found. Does basically the same as regular insert without\r
  87 \-\-allow\-multiple but on other way (in-place). Thus those two options\r
  88 are mutually exclusive.\r
  89 .TP\r
  90 \fB\-m\fR | \fB\-\-allow\-multiple\fR\r
  91 Allow multiple blocks of the same type. By default, old blocks are \r
  92 replaced with the new one.\r
  93 .SS Placement control\r
  94 .TP\r
  95 \fB\-t\fR | \fB\-\-insert\-on\-top\fR\r
  96 Insert on top of the file. The default is to add it at the bottom.\r
  97 .TP\r
  98 \fB\-i\fR | \fB\-\-insert\-after\fR \fIpattern\fR\r
  99 Insert after the first line that matches given pattern.\r
 100 .TP\r
 101 \fB\-f\fR | \fB\-\-insert\-before\fR \fIpattern\fR\r
 102 Insert before the first line that matches given pattern.\r
 103 .PP\r
 104 Line-matching patterns are PCREs (Perl-compatible regular expressions).\r
 105 .SS Manipulating block marks\r
 106 .TP\r
 107 \fB\-c\fR | \fB\-\-comment\fR \fIstring\fR\r
 108 Use alternative comment char/string. The default is shell-style #-sign\r
 109 (bangless she or an octothorpe :\-).\r
 110 .TP\r
 111      \fB\-\-comment\-end\fR \fIstring\fR\r
 112 Use this marker for comment ending. The default is none. \r
 113 Examples: '\-\->', '*/'.\r
 114 .TP\r
 115 \fB\-b\fR | \fB\-\-begin\-mark\fR \fIstring\fR\r
 116 Block starting mark (ie. 'service ftp').\r
 117 .TP\r
 118 \fB\-e\fR | \fB\-\-end\-mark\fR \fIstring\fR\r
 119 Block ending mark (ie. '}').\r
 120 .PP\r
 121 Note that accidental use of these arguments can have\r
 122 harmful effects -- it could be the cause for script to \r
 123 delete content from the beginning mark to the end of the\r
 124 file if no end mark is found. There are measures in place\r
 125 to prevent that, but you should be warned nevertheless.\r
 126 Otheriwise, matching is non-greedy and stops at the first\r
 127 end mark found.\r
 128 .PP\r
 129 You can use \fB%P\fR to insert the \fIpackage\fR argument,\r
 130 and \fB%%\fR to insert a literal % sign into the mark.\r
 131 .SS File handling\r
 132 .TP\r
 133 \fB\-p\fR | \fB\-\-in\-place\fR\r
 134 Try to preserve original inode. Useful when removing blocks\r
 135 from the file so no disk space allocation needs to be done.\r
 136 In that case it is safer than normal mode which creates file\r
 137 anew and replaces the old by renaming it to target name.\r
 138 .TP\r
 139 \fB\-n\fR | \fB\-\-no\-close\fR\r
 140 Do not close and reopen file when editing it in place.\r
 141 Slightly optimized version of the above.\r
 142 .SS Support modes\r
 143 .TP\r
 144 \fB\-h\fR | \fB\-\-help\fR\r
 145 Print usage reference and exit.\r
 146 .TP\r
 147      \fB\-\-version\fR
 148 Print title, version, copyright message, and exit.\r
 149 .\"
 150 .SH "EXIT STATUS"
 151 Upon successful execution of given operation, program returns
 152 exit status of 0 which evaluates to true in shell\-scripting
 153 environment. In case of failure error code 1 is returned.
 154 .\"
 155 .SH COMMENTS
 156 If the File::Copy module is available on system it will be used\r
 157 to create backup copy of the file being updated before the target\r
 158 file gets replaced with the new one, thus increasing reliability.\r
 159 .\"
 160 .SH EXAMPLES
 161 A few examples illustrating basic use-cases follow.
 162 .PP\r
 163 Simple addition of a new block at the end of the file:
 164 .RS\r
 165 .Sp
 166 .Vb 1\r
 167 \&    cp-update aide-cn /etc/aide/aide.conf < aide-cn.ins\r
 168 .Ve
 169 .RE
 170 Replacing or inserting a block at some specific place (Gentoo uses\r
 171 XML config-file so this is also an opportunity to show how to put\r
 172 the inserted block between customized markers):\r
 173 .RS
 174 .Sp
 175 .Vb 4\r
 176 \&    cp-update --insert-before '</Controls>'               \\\r
 177 \&              --comment '<!--' --comment-end ' -->'       \\\r
 178 \&              gentoo-cn /etc/gentoorc < gentoo-cn.ins
 179 .Ve\r
 180 .RE\r
 181 Removing block added with the upper command (here again we mus use\r
 182 the same markers as we did when the block was inserted):\r
 183 .RS
 184 .Sp
 185 .Vb 4\r
 186 \&    cp-update -r --insert-before '</Controls>'            \\\r
 187 \&                 --comment '<!--' --comment-end ' -->'    \\\r
 188 \&                 gentoo-cn /etc/gentoorc
 189 .Ve\r
 190 .RE\r
 191 .\"
 192 .SH ENVIRONMENT
 193 No special environment variables are used.
 194 .\"
 195 .SH FILES
 196 No special files are used for cp-update operation control.
 197 .\"
 198 .SH BUGS
 199 Should be none.
 200 .\"
 201 .SH AUTHORS
 202 Recent version of cp-update is a complete rewrite of the previous one,\r
 203 done by Damir Dzeko. Previous version was written by Hrvoje Niksic and\r
 204 maintaned by Zeljko Boros, Zoran Dzelajlija and Nikola Pavkovic.
 205 .\"
 206 .SH NOTES\r
 207 This man page documents cp-update version 2.0 and is modified occasionally.
 208 For precise insight in its operation don't hesitate to look at the source.\r
 209 .\"
 210 .SH "REPORTING BUGS"
 211 If you find any, we encourage you to send them to CARNet packaging group\r
 212 <paketi-team@CARNet.hr>.
 213 .PP
 214 When sending bug reports, please try to run program in diagnostic mode
 215 and try to send us quality feedback so we could easily locate and
 216 correct the problem.\r
 217 .\"
 218 .SH "SEE ALSO"\r
 219 \fBcarnet-tools\fR(7).\r
 220 .\" End