OpenPKG Specs: openpkg/lsync.8@a2c6460cfb16 (annotated)

openpkg/lsync.8@a2c6460cfb16 (annotated)

openpkg/lsync.8

Mon, 28 Jan 2013 17:37:18 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Mon, 28 Jan 2013 17:37:18 +0100
changeset 758: a2c6460cfb16
parent 13: cb59d6afeb61
permissions: -rw-r--r--

Correct socket error reporting improvement with IPv6 portable code,
after helpful recommendation by Saúl Ibarra Corretgé on OSips devlist.

 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
 ..
 .de Vb \" Begin verbatim text
 .ft CW
 .nf
 .ne \\$1
 ..
 .de Ve \" End verbatim text
 .ft R
 .fi
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
 .\" nothing in troff, for use with C<>.
 .tr \(*W-
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
 .    ds PI pi
 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
 .    ds L" ""
 .    ds R" ""
 .    ds C`
 .    ds C'
 'br\}
 .el\{\
 .    ds -- \|\(em\|
 .    ds PI \(*p
 .    ds L" ``
 .    ds R" ''
 'br\}
 .\"
 .\" Escape single quotes in literal strings from groff's Unicode transform.
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .ie \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
 .el \{\
 .    de IX
 ..
 .\}
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
 .    \" fudge factors for nroff and troff
 .if n \{\
 .    ds #H 0
 .    ds #V .8m
 .    ds #F .3m
 .    ds #[ \f1
 .    ds #] \fP
 .\}
 .if t \{\
 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 .    ds #V .6m
 .    ds #F 0
 .    ds #[ \&
 .    ds #] \&
 .\}
 .    \" simple accents for nroff and troff
 .if n \{\
 .    ds ' \&
 .    ds ` \&
 .    ds ^ \&
 .    ds , \&
 .    ds ~ ~
 .    ds /
 .\}
 .if t \{\
 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 .\}
 .    \" troff and (daisy-wheel) nroff accents
 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 .ds ae a\h'-(\w'a'u*4/10)'e
 .ds Ae A\h'-(\w'A'u*4/10)'E
 .    \" corrections for vroff
 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 .    \" for low resolution devices (crt and lpr)
 .if \n(.H>23 .if \n(.V>19 \
 \{\
 .    ds : e
 .    ds 8 ss
 .    ds o a
 .    ds d- d\h'-1'\(ga
 .    ds D- D\h'-1'\(hy
 .    ds th \o'bp'
 .    ds Th \o'LP'
 .    ds ae ae
 .    ds Ae AE
 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "LSYNC 8"
 .TH LSYNC 8 "OpenPKG" "LSYNC(8)" "OpenPKG"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
 openpkg lsync \- Access Layer Synchronization Tool
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 \&\fBopenpkg lsync\fR
 [\fB\-\-version\fR|\fB\-v\fR]
 [\fB\-\-help\fR|\fB\-h\fR]
 [\fB\-\-init\fR|\fB\-i\fR]
 [\fB\-\-nop\fR|\fB\-n\fR]
 [\fB\-\-quiet\fR|\fB\-q\fR]
 [\fB\-\-trace\fR|\fB\-t\fR]
 [\fB\-\-local\fR|\fB\-l\fR]
 [\fB\-\-uninstall\fR|\fB\-u\fR]
 [\fB\-\-root=\fR\fIroot\fR]
 [\fB\-\-pkgdir=\fR\fIpkgdir\fR]
 [\fB\-\-subdirs=\fR\fIsubdir\fR[,\fIsubdir\fR,...]]
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 This program activates software packages which were locally
 installed in a sub-directory of a package hierarchy (located under
 \&\fIroot\fR/\fIpkgdir\fR/) by managing symbolic links in an access layer
 (located under \fIroot\fR/) corresponding to package installation
 files (found in \fIroot\fR/\fIpkgdir\fR/pkgname/subdir/) which need to be
 collected in global directories (located under \fIroot\fR/subdir/).
 .PP
 The purpose of this is that individual packages can be installed and
 deinstalled seperately without interfering with other packages while
 all packages as a whole still can be treated like a single package
 (installed into the access layer).
 .PP
 The
 actual creation of symbolic links is as following (\*(L"foo\*(R" indicating an
 arbitrary file; \*(L"bar\*(R" indicating an arbitrary package name):
 .IP "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo" 4
 .IX Item "root/bin/foo -> ../pkgdir/bar/bin/foo"
 This activates the user executeable
 \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/bin\fR/foo as \fIroot\fR\fB/bin/\fRfoo. It can
 be found by the shell by placing \fIroot\fR\fB/bin\fR into the environment
 variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/bin:.."\fR).
 .IP "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo" 4
 .IX Item "root/sbin/foo -> ../pkgdir/bar/sbin/foo"
 This activates the system executeable
 \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin\fR/foo as \fIroot\fR\fB/sbin/\fRfoo. It can
 be found by the shell by placing \fIroot\fR\fB/sbin\fR into the environment
 variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/sbin:.."\fR).
 .IP "\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo" 4
 .IX Item "root/man/manN/foo -> ../pkgdir/bar/man/manN/foo"
 This activates the Unix manual page
 \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo as
 \&\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo. It can be found by the \fIman\fR\|(1) tool
 by placing \fIroot\fR\fB/man\fR into the environment variable \f(CW\*(C`MANPATH\*(C'\fR
 (\fBMANPATH="..:\fR\fIroot\fR\fB/man:.."\fR). Keep in mind that \fBopenpkg lsync\fR
 activates any files found in the \fBman/man\f(BIN\fB\fR sub-directory of the
 package, but the \fIman\fR\|(1) tool usually requires the filename scheme
 foo\fB.\fR\fIN\fR before it can find the file.
 .IP "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo" 4
 .IX Item "root/info/foo -> ../pkgdir/bar/info/foo"
 This activates the \s-1GNU\s0 info page \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo
 as \fIroot\fR\fB/info/\fRfoo. It can be found by the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1)
 tools by placing \fIroot\fR\fB/info\fR into the environment variable
 \&\f(CW\*(C`INFOPATH\*(C'\fR (\fBINFOPATH="..:\fR\fIroot\fR\fB/info:.."\fR). Keep in mind that
 \&\fBopenpkg lsync\fR activates any files found in the \fBinfo/\fR sub-directory of the
 package, but the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1) tools usually require the filename
 scheme foo\fB.info\fR before it can find the file.
 .IP "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo" 4
 .IX Item "root/include/foo -> ../pkgdir/bar/include/foo"
 This activates the C header \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/include\fR/foo
 as \fIroot\fR\fB/include/\fRfoo. It can be found by the C/\*(C+ compilers
 by adding \fIroot\fR\fB/include\fR to their include search path (\fBcc ..
 \&\-I\fR\fIroot\fR\fB/include\fR \fB...\fR). Keep in mind that \fBopenpkg lsync\fR activates any
 files found in the \fBinclude/\fR sub-directory of the package, but the
 C/\*(C+ compiler usually by convention use the filename scheme foo\fB.h\fR.
 .IP "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo" 4
 .IX Item "root/lib/foo -> ../pkgdir/bar/lib/foo"
 This activates the C library \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/lib\fR/foo
 as \fIroot\fR\fB/lib/\fRfoo. It can be found by the C/\*(C+ compilers (and
 the linker they use) by adding \fIroot\fR\fB/lib\fR to their library search
 path (\fBcc .. \-L\fR\fIroot\fR\fB/lib\fR \fB...\fR). It can be found by the Unix
 Dynamic Loader by adding \fIroot\fR\fB/lib\fR to the environment variable
 \&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR (\fBLD_LIBRARY_PATH="..:\fR\fIroot\fR\fB/lib:.."\fR).
 Keep in mind that \fBopenpkg lsync\fR activates any files found in the \fBlib/\fR
 sub-directory of the package, but the C/\*(C+ compiler usually require the
 filename scheme \fBlib\fRfoo\fB.a\fR and the Unix Dynamic Loader the filename
 scheme \fBlib\fRfoo\fB.so\fR before they actually can use the file.
 .PP
 It is obvious that more sub-directories in a package installation
 might exist \*(-- for instance \fBshare/\fR, \fBvar/\fR, \fBlibexec/\fR, etc. But
 \&\fBopenpkg lsync\fR intentionally does not link files in those directories into
 corresponding directories of the access layer, because those files do
 not require that they are located in a global area in order to be used.
 So \fBopenpkg lsync\fR only creates the access layer for files where a common area
 is required for (easy) use.
 .SH "SPECIAL FEATURES"
 .IX Header "SPECIAL FEATURES"
 There are two special features supported by \fBopenpkg lsync\fR:
 .IP "\fBRun-Command Files\fR" 4
 .IX Item "Run-Command Files"
 \&\fBopenpkg lsync\fR on startup implicitly reads command line options from
 \&\f(CW\*(C`.lsyncrc\*(C'\fR files. They are searched in all parent directories and in
 the callers home directory. Their contents is prepended to the list of
 given command line options.
 .IP "\fBMultiple Package Versions\fR" 4
 .IX Item "Multiple Package Versions"
 \&\fBopenpkg lsync\fR skips all directories under \fIroot\fR/\fIpkgdir\fR/ which contain
 the pattern \*(L"\-[0\-9]\*(R" in their directory name. On the other hand,
 \&\fBopenpkg lsync\fR follows also symbolic links under \fIroot\fR/\fIpkgdir\fR/.
 This can be used for installing multiple versions of a package and
 switching between them. For instance, if version 1.0 of package
 \&\*(L"foo\*(R" is installed into directory \fIroot\fR/\fIpkgdir\fR/foo\-1.0,
 version 1.1 into \fIroot\fR/\fIpkgdir\fR/foo\-1.1 and version 1.2 into
 \&\fIroot\fR/\fIpkgdir\fR/foo\-1.2, \fBopenpkg lsync\fR does skip all three. To enable
 version 1.1 one just creates a symbolic link \fIroot\fR/\fIpkgdir\fR/foo
 pointing to foo\-1.1. Then \fBopenpkg lsync\fR picks up the files in
 \&\fIroot\fR/\fIpkgdir\fR/foo\-1.1. If you want to temporarily upgrade to
 foo\-1.2, all you have to do is to change the symlink pointing from
 foo\-1.1 to foo\-1.2.
 .IP "\fBTemporarily Deactivated Package\fR" 4
 .IX Item "Temporarily Deactivated Package"
 One can deactivate a package \*(L"foo\*(R" by going to \fIroot\fR/\fIpkgdir\fR/foo/
 and running \*(L"openpkg lsync \-\-local \-\-uninstall\*(R", of course. Alternatively
 one can set the sticky bit on the directory \fIroot\fR/\fIpkgdir\fR/foo.
 Then \fBopenpkg lsync\fR also skips the package. Alternatively, assume
 package \*(L"foo\*(R" as a whole should not be deactivated, but its
 \&\fIroot\fR/\fIpkgdir\fR/foo/lib directory (usually because this directory
 unfortunately contains non-library files), one just sets the sticky bit
 on \fIroot\fR/\fIpkgdir\fR/foo/lib.
 .SH "OPTIONS"
 .IX Header "OPTIONS"
 .IP "\fB\-\-version\fR, \fB\-v\fR" 4
 .IX Item "--version, -v"
 Display program version information only.
 .IP "\fB\-\-help\fR, \fB\-h\fR" 4
 .IX Item "--help, -h"
 Display program usage information only.
 .IP "\fB\-\-init\fR, \fB\-i\fR" 4
 .IX Item "--init, -i"
 Create an initial access layer hierarchy under \fIroot\fR.
 .IP "\fB\-\-nop\fR, \fB\-n\fR" 4
 .IX Item "--nop, -n"
 No Operation \*(-- causes \fBopenpkg lsync\fR to not perform any filesystem
 operations. In conjunction with \fB\-\-trace\fR you can at least see what
 would be executed.
 .IP "\fB\-\-quiet\fR, \fB\-q\fR" 4
 .IX Item "--quiet, -q"
 Forces \fBopenpkg lsync\fR to perform the operations quietly, i.e., without any
 verbose messages.
 .IP "\fB\-\-trace\fR, \fB\-t\fR" 4
 .IX Item "--trace, -t"
 Forces \fBopenpkg lsync\fR to show what filesystem operations are performed.
 .IP "\fB\-\-local\fR, \fB\-l\fR" 4
 .IX Item "--local, -l"
 This restricts the operations to a local package area. This option can
 only be used if you are physically staying below a package sub-directory
 under \fIroot\fR/\fIpkgdir\fR/. For instance, when you are staying in
 \&\fIroot\fR/\fIpkgdir\fR/bar or \fIroot\fR/\fIpkgdir\fR/bar/bin and use \fB\-\-local\fR,
 all operations are restricted to the package \*(L"bar\*(R".
 .IP "\fB\-\-uninstall\fR, \fB\-u\fR" 4
 .IX Item "--uninstall, -u"
 This performs only package uninstallation operations, i.e., only
 symbolic links are removed. This can be used to completely empty the
 access layer. Additionally it is very useful in combination with
 \&\fB\-\-local\fR in order to uninstall a particular package without having to
 remove its files.
 .IP "\fB\-\-root=\fR\fIroot\fR" 4
 .IX Item "--root=root"
 Sets the root directory where the access layer and package subdirectory
 is located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
 (see section \*(L"Current configuration\*(R").
 .IP "\fB\-\-pkgdir=\fR\fIpkgdir\fR" 4
 .IX Item "--pkgdir=pkgdir"
 Sets the sub-directory under the root directory where packages are
 located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR (see
 section \*(L"Current configuration\*(R").
 .IP "\fB\-\-subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]" 4
 .IX Item "--subdirs=subdirs[,subdir,...]"
 Sets one or more sub-directories of the access layer on which \fBopenpkg lsync\fR
 should act. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
 (see section \*(L"Current configuration\*(R").
 .SH "RESULTS"
 .IX Header "RESULTS"
 This program uses the following return codes on exit: 0 (operation
 successful), 1 (system error), 2 (command line error) and 3 (other user
 error).
 .SH "HISTORY"
 .IX Header "HISTORY"
 The idea of filesystem access layers consisting of symbolic links
 pointing to actual package installation areas is a rather old one. It
 dates back to the early days of Unix and was implemented many times over
 the last decades. One of many implementation was \fBGenOPT\fR, written by
 Ralf S. Engelschall for sd&m GmbH & Co \s-1KG\s0, Munich in 1992. The name
 indicates the programs purpose: to generate symbolic links in an access
 layer which was located under \f(CW\*(C`/opt\*(C'\fR. \fBGenOPT\fR was very flexible, but
 hence also very complex. Because of lack of documentation it was never
 released and so only used at sd&m and on all machines which were under
 control of Ralf S. Engelschall.
 .PP
 For Cable & Wireless, Munich, the old \fBGenOPT\fR principle was again
 needed to manage the \f(CW\*(C`/cw/local\*(C'\fR area on their servers. For this in
 November 2000 the functionality of \fBGenOPT\fR was revised, heavily
 stripped down and finally implemented from scratch. The result is the
 current \fBopenpkg lsync\fR.
 .SH "AUTHOR"
 .IX Header "AUTHOR"
 .Vb 3
 \& Ralf S. Engelschall
 \& rse@engelschall.com
 \& www.engelschall.com
 .Ve

OpenPKG Specs / annotate

openpkg/lsync.8@a2c6460cfb16 (annotated)

openpkg/lsync.8