This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Merge branch 'fix-grammar' into blead
[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<fcntl.h> file.
15 Unlike the old mechanism of requiring a translated F<fcntl.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 use strict;
59
60 use Exporter 'import';
61 require XSLoader;
62 our $VERSION = '1.15';
63
64 XSLoader::load();
65
66 # Named groups of exports
67 our %EXPORT_TAGS = (
68     'flock'   => [qw(LOCK_SH LOCK_EX LOCK_NB LOCK_UN)],
69     'Fcompat' => [qw(FAPPEND FASYNC FCREAT FDEFER FDSYNC FEXCL FLARGEFILE
70                      FNDELAY FNONBLOCK FRSYNC FSYNC FTRUNC)],
71     'seek'    => [qw(SEEK_SET SEEK_CUR SEEK_END)],
72     'mode'    => [qw(S_ISUID S_ISGID S_ISVTX S_ISTXT
73                      _S_IFMT S_IFREG S_IFDIR S_IFLNK
74                      S_IFSOCK S_IFBLK S_IFCHR S_IFIFO S_IFWHT S_ENFMT
75                      S_IRUSR S_IWUSR S_IXUSR S_IRWXU
76                      S_IRGRP S_IWGRP S_IXGRP S_IRWXG
77                      S_IROTH S_IWOTH S_IXOTH S_IRWXO
78                      S_IREAD S_IWRITE S_IEXEC
79                      S_ISREG S_ISDIR S_ISLNK S_ISSOCK
80                      S_ISBLK S_ISCHR S_ISFIFO
81                      S_ISWHT S_ISENFMT          
82                      S_IFMT S_IMODE
83                   )],
84 );
85
86 # Items to export into callers namespace by default
87 # (move infrequently used names to @EXPORT_OK below)
88 our @EXPORT =
89   qw(
90         FD_CLOEXEC
91         F_ALLOCSP
92         F_ALLOCSP64
93         F_COMPAT
94         F_DUP2FD
95         F_DUPFD
96         F_EXLCK
97         F_FREESP
98         F_FREESP64
99         F_FSYNC
100         F_FSYNC64
101         F_GETFD
102         F_GETFL
103         F_GETLK
104         F_GETLK64
105         F_GETOWN
106         F_NODNY
107         F_POSIX
108         F_RDACC
109         F_RDDNY
110         F_RDLCK
111         F_RWACC
112         F_RWDNY
113         F_SETFD
114         F_SETFL
115         F_SETLK
116         F_SETLK64
117         F_SETLKW
118         F_SETLKW64
119         F_SETOWN
120         F_SHARE
121         F_SHLCK
122         F_UNLCK
123         F_UNSHARE
124         F_WRACC
125         F_WRDNY
126         F_WRLCK
127         O_ACCMODE
128         O_ALIAS
129         O_APPEND
130         O_ASYNC
131         O_BINARY
132         O_CREAT
133         O_DEFER
134         O_DIRECT
135         O_DIRECTORY
136         O_DSYNC
137         O_EXCL
138         O_EXLOCK
139         O_LARGEFILE
140         O_NDELAY
141         O_NOCTTY
142         O_NOFOLLOW
143         O_NOINHERIT
144         O_NONBLOCK
145         O_RANDOM
146         O_RAW
147         O_RDONLY
148         O_RDWR
149         O_RSRC
150         O_RSYNC
151         O_SEQUENTIAL
152         O_SHLOCK
153         O_SYNC
154         O_TEMPORARY
155         O_TEXT
156         O_TRUNC
157         O_WRONLY
158      );
159
160 # Other items we are prepared to export if requested
161 our @EXPORT_OK = (qw(
162         DN_ACCESS
163         DN_ATTRIB
164         DN_CREATE
165         DN_DELETE
166         DN_MODIFY
167         DN_MULTISHOT
168         DN_RENAME
169         F_GETLEASE
170         F_GETPIPE_SZ
171         F_GETSIG
172         F_NOTIFY
173         F_SETLEASE
174         F_SETPIPE_SZ
175         F_SETSIG
176         LOCK_MAND
177         LOCK_READ
178         LOCK_RW
179         LOCK_WRITE
180         O_ALT_IO
181         O_EVTONLY
182         O_IGNORE_CTTY
183         O_NOATIME
184         O_NOLINK
185         O_NOSIGPIPE
186         O_NOTRANS
187         O_SYMLINK
188         O_TTY_INIT
189 ), map {@{$_}} values %EXPORT_TAGS);
190
191 1;