.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" 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 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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "mnt::gmirror::ports::devel::p5-Include::work::Include-1.02a::Include 3"
.TH mnt::gmirror::ports::devel::p5-Include::work::Include-1.02a::Include 3 "1996-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Include \- allow use #defines from C header files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Include qw(-I /some/path/of/mine);
\&    use Include q<sys/types.h>;
\&    use Include q<sys/types.h> "/[A-Z]/";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Include module implements a method of using #define constants from
C header files. It does this by putting an extra level of indirection
on the use operator.
.PP
To enhance performance a cache scheme is used. When a new module is
required the cache is checked first, if the package is not found then
it will be generated from the C header files.
.PP
Include can be configured to place any generated packages into the cache
automatically, for security reasons this is turned off by default.
.PP
There are three ways in which the \f(CW\*(C`use Include\*(C'\fR statement can be used.
.PP
.Vb 1
\&    use Include qw(-I /some/path/of/mine);
.Ve
.PP
Will unshift the directory \fI/some/path/of/mine\fR onto the search path used
so that subsequent searches for .h header files will search the given
directories first.
.PP
.Vb 2
\&    use Include q<sys/types.h>;
\&    use Include q<sys/types.h> "/[A-Z]/";
.Ve
.PP
Both of these will define all the constants found in <sys/types.h> and
any header files included by it. The first will export all of these
into the calling package, but the second will only export defined
macros that contain an unppercase character.
.Sh "Subroutines"
.IX Subsection "Subroutines"
Under normal use the Include package is only used via the use/import interface.
But there are some routines that are defined.
.IP "CacheOn" 4
.IX Item "CacheOn"
This subroutine will cause the Include module to save any generated packages
into the cache.
.ie n .IP "Generate( @headers )" 4
.el .IP "Generate( \f(CW@headers\fR )" 4
.IX Item "Generate( @headers )"
This subroutine will force the generation of the given header files, and
any files included in them, reguardless of whether they are currently in
the cache. If cache writing is turned on then the cache files will be 
overwritten.
.ie n .IP "Search( @dirs )" 4
.el .IP "Search( \f(CW@dirs\fR )" 4
.IX Item "Search( @dirs )"
This subroutine will unshift the given directories onto the search
path used for locating the header files.
.SH "NOTE"
.IX Header "NOTE"
Having the cache writing turned on by default if a potential security
risk as all users will need write rights to the cache directory
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Barr <Graham.Barr@tiuk.ti.com>
.SH "REVISION"
.IX Header "REVISION"
$Revision: 1.2 $
.SH "BUGS"
.IX Header "BUGS"
None known
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Parsing code is based on the h2ph program which comes with the perl
distribution. All other code is Copyright (c) 1995 Graham Barr. All
rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.