cp-update.1

   1 .\" Copied from from Pod::Man template\r
   2 .\" Wed, 23 Mar 2005 11:51:08 +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 2005" 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\-m\fR | \fB\-\-allow\-multiple\fR\r
  85 Allow multiple blocks of the same type. By default, old blocks are \r
  86 replaced with the new one.\r
  87 .TP\r
  88 \fB\-h\fR | \fB\-\-help\fR\r
  89 Print usage reference and exit.\r
  90 .TP\r
  91      \fB\-\-version\fR
  92 Print title, version, copyright message, and exit.\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 .TP\r
 104 \fB\-R\fR | \fB\-\-regexp\-match\fR | \fB\-\-regexp\fR\r
 105 Use regexp mode for line matching.\r
 106 .SS Manipulating block marks\r
 107 .TP\r
 108 \fB\-c\fR | \fB\-\-comment\fR \fIstring\fR\r
 109 Use alternative comment char/string. The default is shell-style #-sign\r
 110 (bangless she or an octothorpe :\-).\r
 111 .TP\r
 112      \fB\-\-comment\-end\fR \fIstring\fR\r
 113 Use this marker for comment ending. The default is none. \r
 114 Examples: '\-\->', '*/'.\r
 115 .TP\r
 116 \fB\-b\fR | \fB\-\-begin\-mark\fR \fIstring\fR\r
 117 Block starting mark (ie. 'service ftp').\r
 118 .TP\r
 119 \fB\-e\fR | \fB\-\-end\-mark\fR \fIstring\fR\r
 120 Block ending mark (ie. '}').\r
 121 .PP\r
 122 Note that accidental use of these arguments can have\r
 123 harmful effects -- it could be the cause for script to \r
 124 delete content from the beginning mark to the end of the\r
 125 file if no end mark is found. There are measures in place\r
 126 to prevent that, but you should be warned nevertheless.\r
 127 Otheriwise, matching is non-greedy and stops at the first\r
 128 end mark found.\r
 129 .PP\r
 130 You can use \fB%P\fR to insert the \fIpackage\fR argument,\r
 131 and \fB%%\fR to insert a literal % sign into the mark.\r
 132 .SS File handling\r
 133 .TP\r
 134 \fB\-p\fR | \fB\-\-in\-place\fR\r
 135 Try to preserve original inode. Useful when removing blocks\r
 136 from the file so no disk space allocation needs to be done.\r
 137 In that case it is safer than normal mode which creates file\r
 138 anew and replaces the old by renaming it to target name.\r
 139 .TP\r
 140 \fB\-n\fR | \fB\-\-no\-close\fR\r
 141 Do not close and reopen file when editing it in place.\r
 142 Slightly optimized version of the above.\r
 143 .\"
 144 .SH "EXIT STATUS"
 145 Upon successful execution of given operation, program returns
 146 exit status of 0 which evaluates to true in shell\-scripting
 147 environment. In case of failure error code 1 is returned.
 148 .\"
 149 .SH COMMENTS
 150 If the File::Copy module is available on system it will be used\r
 151 to create backup copy of the file being updated before the target\r
 152 file gets replaced with the new one, thus increasing reliability.\r
 153 .\"
 154 .SH EXAMPLES
 155 A few examples illustrating basic use-cases follow.
 156 .PP\r
 157 Simple addition of a new block at the end of the file:
 158 .RS\r
 159 .Sp
 160 .Vb 1\r
 161 \&    cp-update aide-cn /etc/aide/aide.conf < aide-cn.ins\r
 162 .Ve
 163 .RE
 164 Replacing or inserting a block at some specific place (Gentoo uses\r
 165 XML config-file so this is also an opportunity to show how to put\r
 166 the inserted block between customized markers):\r
 167 .RS
 168 .Sp
 169 .Vb 4\r
 170 \&    cp-update --regexp --insert-before '</Controls>'      \\\r
 171 \&              --comment '<!--' --comment-end ' -->'       \\\r
 172 \&              gentoo-cn /etc/gentoorc < gentoo-cn.ins
 173 .Ve\r
 174 .RE\r
 175 Removing block added with the upper command (here again we mus use\r
 176 the same markers as we did when the block was inserted):\r
 177 .RS
 178 .Sp
 179 .Vb 4\r
 180 \&    cp-update -r --regexp --insert-before '</Controls>'   \\\r
 181 \&              --comment '<!--' --comment-end ' -->'       \\\r
 182 \&              gentoo-cn /etc/gentoorc
 183 .Ve\r
 184 .RE\r
 185 .\"
 186 .SH ENVIRONMENT
 187 No special environment variables are used.
 188 .\"
 189 .SH FILES
 190 No special files are used for cp-update operation control.
 191 .\"
 192 .SH BUGS
 193 Should be none.
 194 .\"
 195 .SH AUTHORS
 196 Recent version of cp-update is a complete rewrite of the previous one,\r
 197 done by Damir Dzeko. Previous version was written by Hrvoje Niksic and\r
 198 maintaned by Zeljko Boros, Zoran Dzelajlija and Nikola Pavkovic.
 199 .\"
 200 .SH NOTES\r
 201 This man page documents cp-update version 2.0 and is modified occasionally.
 202 For precise insight in its operation don't hesitate to look at the source.\r
 203 .\"
 204 .SH "REPORTING BUGS"
 205 If you find any, we encourage you to send them to CARNet packaging group\r
 206 at SRCE <paketi@srce.hr>.
 207 .PP
 208 When sending bug reports, please try to run program in diagnostic mode
 209 and try to send us quality feedback so we could easily locate and
 210 correct the problem.\r
 211 .\"
 212 .SH "SEE ALSO"\r
 213 \fBcarnet-tools\fR(7).\r
 214 .\" End