This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate mainline.
[perl5.git] / ext / Fcntl / Fcntl.pm
1 package Fcntl;
2
3 =head1 NAME
4
5 Fcntl - load the C Fcntl.h defines
6
7 =head1 SYNOPSIS
8
9     use Fcntl;
10     use Fcntl qw(:DEFAULT :flock);
11
12 =head1 DESCRIPTION
13
14 This module is just a translation of the C F<fnctl.h> file.
15 Unlike the old mechanism of requiring a translated F<fnctl.ph>
16 file, this uses the B<h2xs> program (see the Perl source distribution)
17 and your native C compiler.  This means that it has a 
18 far more likely chance of getting the numbers right.
19
20 =head1 NOTE
21
22 Only C<#define> symbols get translated; you must still correctly
23 pack up your own arguments to pass as args for locking functions, etc.
24
25 =head1 EXPORTED SYMBOLS
26
27 By default your system's F_* and O_* constants (eg, F_DUPFD and
28 O_CREAT) and the FD_CLOEXEC constant are exported into your namespace.
29
30 You can request that the flock() constants (LOCK_SH, LOCK_EX, LOCK_NB
31 and LOCK_UN) be provided by using the tag C<:flock>.  See L<Exporter>.
32
33 You can request that the old constants (FAPPEND, FASYNC, FCREAT,
34 FDEFER, FEXCL, FNDELAY, FNONBLOCK, FSYNC, FTRUNC) be provided for
35 compatibility reasons by using the tag C<:Fcompat>.  For new
36 applications the newer versions of these constants are suggested
37 (O_APPEND, O_ASYNC, O_CREAT, O_DEFER, O_EXCL, O_NDELAY, O_NONBLOCK,
38 O_SYNC, O_TRUNC).
39
40 For ease of use also the SEEK_* constants (for seek() and sysseek(),
41 e.g. SEEK_END) and the S_I* constants (for chmod() and stat()) are
42 available for import.  They can be imported either separately or using
43 the tags C<:seek> and C<:mode>.
44
45 Please refer to your native fcntl(2), open(2), fseek(3), lseek(2)
46 (equal to Perl's seek() and sysseek(), respectively), and chmod(2)
47 documentation to see what constants are implemented in your system.
48
49 See L<perlopentut> to learn about the uses of the O_* constants
50 with sysopen().
51
52 See L<perlfunc/seek> and L<perlfunc/sysseek> about the SEEK_* constants.
53
54 See L<perlfunc/stat> about the S_I* constants.
55
56 =cut
57
58 our($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS, $AUTOLOAD);
59
60 require Exporter;
61 use XSLoader ();
62 @ISA = qw(Exporter);
63 $VERSION = "1.03";
64 # Items to export into callers namespace by default
65 # (move infrequently used names to @EXPORT_OK below)
66 @EXPORT =
67   qw(
68         FD_CLOEXEC
69         F_ALLOCSP
70         F_ALLOCSP64
71         F_COMPAT
72         F_DUP2FD
73         F_DUPFD
74         F_EXLCK
75         F_FREESP
76         F_FREESP64
77         F_FSYNC
78         F_FSYNC64
79         F_GETFD
80         F_GETFL
81         F_GETLK
82         F_GETLK64
83         F_GETOWN
84         F_NODNY
85         F_POSIX
86         F_RDACC
87         F_RDDNY
88         F_RDLCK
89         F_RWACC
90         F_RWDNY
91         F_SETFD
92         F_SETFL
93         F_SETLK
94         F_SETLK64
95         F_SETLKW
96         F_SETLKW64
97         F_SETOWN
98         F_SHARE
99         F_SHLCK
100         F_UNLCK
101         F_UNSHARE
102         F_WRACC
103         F_WRDNY
104         F_WRLCK
105         O_ACCMODE
106         O_ALIAS
107         O_APPEND
108         O_ASYNC
109         O_BINARY
110         O_CREAT
111         O_DEFER
112         O_DIRECT
113         O_DIRECTORY
114         O_DSYNC
115         O_EXCL
116         O_EXLOCK
117         O_LARGEFILE
118         O_NDELAY
119         O_NOCTTY
120         O_NOFOLLOW
121         O_NOINHERIT
122         O_NONBLOCK
123         O_RANDOM
124         O_RAW
125         O_RDONLY
126         O_RDWR
127         O_RSRC
128         O_RSYNC
129         O_SEQUENTIAL
130         O_SHLOCK
131         O_SYNC
132         O_TEMPORARY
133         O_TEXT
134         O_TRUNC
135         O_WRONLY
136      );
137
138 # Other items we are prepared to export if requested
139 @EXPORT_OK = qw(
140         FAPPEND
141         FASYNC
142         FCREAT
143         FDEFER
144         FDSYNC
145         FEXCL
146         FLARGEFILE
147         FNDELAY
148         FNONBLOCK
149         FRSYNC
150         FSYNC
151         FTRUNC
152         LOCK_EX
153         LOCK_NB
154         LOCK_SH
155         LOCK_UN
156         S_ISUID S_ISGID S_ISVTX S_ISTXT
157         _S_IFMT S_IFREG S_IFDIR S_IFLNK
158         S_IFSOCK S_IFBLK S_IFCHR S_IFIFO S_IFWHT S_ENFMT
159         S_IRUSR S_IWUSR S_IXUSR S_IRWXU
160         S_IRGRP S_IWGRP S_IXGRP S_IRWXG
161         S_IROTH S_IWOTH S_IXOTH S_IRWXO
162         S_IREAD S_IWRITE S_IEXEC
163         &S_ISREG &S_ISDIR &S_ISLNK &S_ISSOCK &S_ISBLK &S_ISCHR &S_ISFIFO
164         &S_ISWHT &S_ISENFMT &S_IFMT &S_IMODE
165         SEEK_SET
166         SEEK_CUR
167         SEEK_END
168 );
169 # Named groups of exports
170 %EXPORT_TAGS = (
171     'flock'   => [qw(LOCK_SH LOCK_EX LOCK_NB LOCK_UN)],
172     'Fcompat' => [qw(FAPPEND FASYNC FCREAT FDEFER FDSYNC FEXCL FLARGEFILE
173                      FNDELAY FNONBLOCK FRSYNC FSYNC FTRUNC)],
174     'seek'    => [qw(SEEK_SET SEEK_CUR SEEK_END)],
175     'mode'    => [qw(S_ISUID S_ISGID S_ISVTX S_ISTXT
176                      _S_IFMT S_IFREG S_IFDIR S_IFLNK
177                      S_IFSOCK S_IFBLK S_IFCHR S_IFIFO S_IFWHT S_ENFMT
178                      S_IRUSR S_IWUSR S_IXUSR S_IRWXU
179                      S_IRGRP S_IWGRP S_IXGRP S_IRWXG
180                      S_IROTH S_IWOTH S_IXOTH S_IRWXO
181                      S_IREAD S_IWRITE S_IEXEC
182                      S_ISREG S_ISDIR S_ISLNK S_ISSOCK
183                      S_ISBLK S_ISCHR S_ISFIFO
184                      S_ISWHT S_ISENFMT          
185                      S_IFMT S_IMODE
186                   )],
187 );
188
189 sub S_IFMT  { @_ ? ( $_[0] & _S_IFMT() ) : _S_IFMT()  }
190 sub S_IMODE { $_[0] & 07777 }
191
192 sub S_ISREG    { ( $_[0] & _S_IFMT() ) == S_IFREG()   }
193 sub S_ISDIR    { ( $_[0] & _S_IFMT() ) == S_IFDIR()   }
194 sub S_ISLNK    { ( $_[0] & _S_IFMT() ) == S_IFLNK()   }
195 sub S_ISSOCK   { ( $_[0] & _S_IFMT() ) == S_IFSOCK()  }
196 sub S_ISBLK    { ( $_[0] & _S_IFMT() ) == S_IFBLK()   }
197 sub S_ISCHR    { ( $_[0] & _S_IFMT() ) == S_IFCHR()   }
198 sub S_ISFIFO   { ( $_[0] & _S_IFMT() ) == S_IFIFO()   }
199 sub S_ISWHT    { ( $_[0] & _S_IFMT() ) == S_IFWHT()   }
200 sub S_ISENFMT  { ( $_[0] & _S_IFMT() ) == S_IFENFMT() }
201
202 sub AUTOLOAD {
203     (my $constname = $AUTOLOAD) =~ s/.*:://;
204     my $val = constant($constname);
205     if ($! != 0) {
206         if ($! =~ /Invalid/ || $!{EINVAL}) {
207             $AutoLoader::AUTOLOAD = $AUTOLOAD;
208             goto &AutoLoader::AUTOLOAD;
209         }
210         else {
211             my ($pack,$file,$line) = caller;
212             die "Your vendor has not defined Fcntl macro $constname, used at $file line $line.
213 ";
214         }
215     }
216     *$AUTOLOAD = sub { $val };
217     goto &$AUTOLOAD;
218 }
219
220 XSLoader::load 'Fcntl', $VERSION;
221
222 1;