From: Damir Dzeko Date: Tue, 29 Mar 2005 17:37:47 +0000 (+0000) Subject: r30: manpage for cp-update X-Git-Tag: debian/3.0.0~76 X-Git-Url: http://ftp.carnet.hr/pub/carnet-debian/scm?a=commitdiff_plain;h=d006aa90386744d0e56ea0b5aec4b31d387a6896;p=carnet-tools-cn.git r30: manpage for cp-update --- diff --git a/cp-update.1 b/cp-update.1 new file mode 100644 index 0000000..f36368d --- /dev/null +++ b/cp-update.1 @@ -0,0 +1,215 @@ +.\" Copied from from Pod::Man template +.\" Wed, 23 Mar 2005 11:51:08 +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 2005" 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\-m\fR | \fB\-\-allow\-multiple\fR +Allow multiple blocks of the same type. By default, old blocks are +replaced with the new one. +.TP +\fB\-h\fR | \fB\-\-help\fR +Print usage reference and exit. +.TP + \fB\-\-version\fR +Print title, version, copyright message, and exit. +.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. +.TP +\fB\-R\fR | \fB\-\-regexp\-match\fR | \fB\-\-regexp\fR +Use regexp mode for line matching. +.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. +.\" +.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 --regexp --insert-before '' \\ +\& --comment '' \\ +\& 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 --regexp --insert-before '' \\ +\& --comment '' \\ +\& 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 +at SRCE . +.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" +.BR carnet-tools(8), +.BR dpkg-divert(8). +.\" End