.\" Copied from from Pod::Man template
.\" Wed, 14 Mar 2006 21:15:00 +0100
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.IX Title "cp-update 1"
.TH cp-update 1 "March 2006" CARNet "CARNet Packaging Tools"
.SH NAME
cp-update \- versatile line-based file updating tool
.\"
.SH SYNOPSIS
.B cp-update
[\fIoptions\fR] \fIpackage\fR \fIfile\fR < \fIstdin-content\fR
.\"
.SH DESCRIPTION
This tool is usually used in postinst scripts of CARNet "\-cn" packages
to modify configuration files of other pre-installed packages. It eases
task of manipulating portions of configuration files by tagging blocks
of content with recognizable begin and end marks. Configuration block
marked that way can later be easily updated or removed.
.PP
When making modifications to filesystem, \fBcp-update\fR tries to do it
as atomically as possible, thus shortening the window when the system,
or some particular package, can be left in an unusable state.
.PP
Default mode of execution is to add the block read from standard input
to the configuration file, enclosed by begin and end marks, or replace
existing block identified by \fIpackage\fR \- usually the package name.
.PP
The blocks added to configuration file using default options look like:
.Sp
.Vb 5
\&  # Begin update by CARNet package test1 -- DO NOT DELETE THIS LINE!
\&  Block inserted by test1,
\&  using default options.
\&  This is the third line.
\&  # End update by CARNet package test1 -- DO NOT DELETE THIS LINE!
.Ve
.\"
.SH OPTIONS
Options provide a way to specify different operation mode, placement,
block marking and file handling.
.SS General options
.Sp
.TP
\fB\-r\fR | \fB\-\-remove\fR
Remove entry \fIpackage\fR from \fIfile\fR. Default is to add lines 
from stdin.
.TP
\fB\-x\fR | \fB\-\-change\fR
Modify existing block, or add it if it does not exist but the begin 
mark can be found. Does basically the same as regular insert without
\-\-allow\-multiple but on other way (in-place). Thus those two options
are mutually exclusive.
.TP
\fB\-m\fR | \fB\-\-allow\-multiple\fR
Allow multiple blocks of the same type. By default, old blocks are 
replaced with the new one.
.SS Placement control
.TP
\fB\-t\fR | \fB\-\-insert\-on\-top\fR
Insert on top of the file. The default is to add it at the bottom.
.TP
\fB\-i\fR | \fB\-\-insert\-after\fR \fIpattern\fR
Insert after the first line that matches given pattern.
.TP
\fB\-f\fR | \fB\-\-insert\-before\fR \fIpattern\fR
Insert before the first line that matches given pattern.
.PP
Line-matching patterns are PCREs (Perl-compatible regular expressions).
.SS Manipulating block marks
.TP
\fB\-c\fR | \fB\-\-comment\fR \fIstring\fR
Use alternative comment char/string. The default is shell-style #-sign
(bangless she or an octothorpe :\-).
.TP
     \fB\-\-comment\-end\fR \fIstring\fR
Use this marker for comment ending. The default is none. 
Examples: '\-\->', '*/'.
.TP
\fB\-b\fR | \fB\-\-begin\-mark\fR \fIstring\fR
Block starting mark (ie. 'service ftp').
.TP
\fB\-e\fR | \fB\-\-end\-mark\fR \fIstring\fR
Block ending mark (ie. '}').
.PP
Note that accidental use of these arguments can have
harmful effects -- it could be the cause for script to 
delete content from the beginning mark to the end of the
file if no end mark is found. There are measures in place
to prevent that, but you should be warned nevertheless.
Otheriwise, matching is non-greedy and stops at the first
end mark found.
.PP
You can use \fB%P\fR to insert the \fIpackage\fR argument,
and \fB%%\fR to insert a literal % sign into the mark.
.SS File handling
.TP
\fB\-p\fR | \fB\-\-in\-place\fR
Try to preserve original inode. Useful when removing blocks
from the file so no disk space allocation needs to be done.
In that case it is safer than normal mode which creates file
anew and replaces the old by renaming it to target name.
.TP
\fB\-n\fR | \fB\-\-no\-close\fR
Do not close and reopen file when editing it in place.
Slightly optimized version of the above.
.SS Support modes
.TP
\fB\-h\fR | \fB\-\-help\fR
Print usage reference and exit.
.TP
     \fB\-\-version\fR
Print title, version, copyright message, and exit.
.\"
.SH "EXIT STATUS"
Upon successful execution of given operation, program returns 
exit status of 0 which evaluates to true in shell\-scripting 
environment. In case of failure error code 1 is returned.
.\"
.SH COMMENTS
If the File::Copy module is available on system it will be used
to create backup copy of the file being updated before the target
file gets replaced with the new one, thus increasing reliability.
.\"
.SH EXAMPLES
A few examples illustrating basic use-cases follow.
.PP
Simple addition of a new block at the end of the file:
.RS
.Sp
.Vb 1
\&    cp-update aide-cn /etc/aide/aide.conf < aide-cn.ins
.Ve
.RE
Replacing or inserting a block at some specific place (Gentoo uses
XML config-file so this is also an opportunity to show how to put
the inserted block between customized markers):
.RS
.Sp
.Vb 4
\&    cp-update --insert-before '</Controls>'               \\
\&              --comment '<!--' --comment-end ' -->'       \\
\&              gentoo-cn /etc/gentoorc < gentoo-cn.ins
.Ve
.RE
Removing block added with the upper command (here again we mus use
the same markers as we did when the block was inserted):
.RS
.Sp
.Vb 4
\&    cp-update -r --insert-before '</Controls>'            \\
\&                 --comment '<!--' --comment-end ' -->'    \\
\&                 gentoo-cn /etc/gentoorc
.Ve
.RE
.\"
.SH ENVIRONMENT
No special environment variables are used.
.\"
.SH FILES
No special files are used for cp-update operation control.
.\"
.SH BUGS
Should be none.
.\"
.SH AUTHORS
Recent version of cp-update is a complete rewrite of the previous one,
done by Damir Dzeko. Previous version was written by Hrvoje Niksic and
maintaned by Zeljko Boros, Zoran Dzelajlija and Nikola Pavkovic.
.\"
.SH NOTES
This man page documents cp-update version 2.0 and is modified occasionally.
For precise insight in its operation don't hesitate to look at the source.
.\"
.SH "REPORTING BUGS"
If you find any, we encourage you to send them to CARNet packaging group
<paketi-team@CARNet.hr>.
.PP
When sending bug reports, please try to run program in diagnostic mode
and try to send us quality feedback so we could easily locate and
correct the problem.
.\"
.SH "SEE ALSO"
\fBcarnet-tools\fR(7).
.\" End