1Opcode(3pm)            Perl Programmers Reference Guide            Opcode(3pm)
2
3
4

NAME

6       Opcode - Disable named opcodes when compiling perl code
7

SYNOPSIS

9         use Opcode;
10

DESCRIPTION

12       Perl code is always compiled into an internal format before execution.
13
14       Evaluating perl code (e.g. via "eval" or "do 'file'") causes the code
15       to be compiled into an internal format and then, provided there was no
16       error in the compilation, executed.  The internal format is based on
17       many distinct opcodes.
18
19       By default no opmask is in effect and any code can be compiled.
20
21       The Opcode module allow you to define an operator mask to be in effect
22       when perl next compiles any code.  Attempting to compile code which
23       contains a masked opcode will cause the compilation to fail with an
24       error. The code will not be executed.
25

NOTE

27       The Opcode module is not usually used directly. See the ops pragma and
28       Safe modules for more typical uses.
29

WARNING

31       The authors make no warranty, implied or otherwise, about the
32       suitability of this software for safety or security purposes.
33
34       The authors shall not in any case be liable for special, incidental,
35       consequential, indirect or other similar damages arising from the use
36       of this software.
37
38       Your mileage will vary. If in any doubt do not use it.
39

Operator Names and Operator Lists

41       The canonical list of operator names is the contents of the array
42       PL_op_name defined and initialised in file opcode.h of the Perl source
43       distribution (and installed into the perl library).
44
45       Each operator has both a terse name (its opname) and a more verbose or
46       recognisable descriptive name. The opdesc function can be used to
47       return a list of descriptions for a list of operators.
48
49       Many of the functions and methods listed below take a list of operators
50       as parameters. Most operator lists can be made up of several types of
51       element. Each element can be one of
52
53       an operator name (opname)
54               Operator names are typically small lowercase words like
55               enterloop, leaveloop, last, next, redo etc. Sometimes they are
56               rather cryptic like gv2cv, i_ncmp and ftsvtx.
57
58       an operator tag name (optag)
59               Operator tags can be used to refer to groups (or sets) of
60               operators.  Tag names always begin with a colon. The Opcode
61               module defines several optags and the user can define others
62               using the define_optag function.
63
64       a negated opname or optag
65               An opname or optag can be prefixed with an exclamation mark,
66               e.g., !mkdir.  Negating an opname or optag means remove the
67               corresponding ops from the accumulated set of ops at that
68               point.
69
70       an operator set (opset)
71               An opset as a binary string of approximately 44 bytes which
72               holds a set or zero or more operators.
73
74               The opset and opset_to_ops functions can be used to convert
75               from a list of operators to an opset and vice versa.
76
77               Wherever a list of operators can be given you can use one or
78               more opsets.  See also Manipulating Opsets below.
79

Opcode Functions

81       The Opcode package contains functions for manipulating operator names
82       tags and sets. All are available for export by the package.
83
84       opcodes In a scalar context opcodes returns the number of opcodes in
85               this version of perl (around 350 for perl-5.7.0).
86
87               In a list context it returns a list of all the operator names.
88               (Not yet implemented, use @names = opset_to_ops(full_opset).)
89
90       opset (OP, ...)
91               Returns an opset containing the listed operators.
92
93       opset_to_ops (OPSET)
94               Returns a list of operator names corresponding to those
95               operators in the set.
96
97       opset_to_hex (OPSET)
98               Returns a string representation of an opset. Can be handy for
99               debugging.
100
101       full_opset
102               Returns an opset which includes all operators.
103
104       empty_opset
105               Returns an opset which contains no operators.
106
107       invert_opset (OPSET)
108               Returns an opset which is the inverse set of the one supplied.
109
110       verify_opset (OPSET, ...)
111               Returns true if the supplied opset looks like a valid opset (is
112               the right length etc) otherwise it returns false. If an
113               optional second parameter is true then verify_opset will croak
114               on an invalid opset instead of returning false.
115
116               Most of the other Opcode functions call verify_opset
117               automatically and will croak if given an invalid opset.
118
119       define_optag (OPTAG, OPSET)
120               Define OPTAG as a symbolic name for OPSET. Optag names always
121               start with a colon ":".
122
123               The optag name used must not be defined already (define_optag
124               will croak if it is already defined). Optag names are global to
125               the perl process and optag definitions cannot be altered or
126               deleted once defined.
127
128               It is strongly recommended that applications using Opcode
129               should use a leading capital letter on their tag names since
130               lowercase names are reserved for use by the Opcode module. If
131               using Opcode within a module you should prefix your tags names
132               with the name of your module to ensure uniqueness and thus
133               avoid clashes with other modules.
134
135       opmask_add (OPSET)
136               Adds the supplied opset to the current opmask. Note that there
137               is currently no mechanism for unmasking ops once they have been
138               masked.  This is intentional.
139
140       opmask  Returns an opset corresponding to the current opmask.
141
142       opdesc (OP, ...)
143               This takes a list of operator names and returns the
144               corresponding list of operator descriptions.
145
146       opdump (PAT)
147               Dumps to STDOUT a two column list of op names and op
148               descriptions.  If an optional pattern is given then only lines
149               which match the (case insensitive) pattern will be output.
150
151               It's designed to be used as a handy command line utility:
152
153                       perl -MOpcode=opdump -e opdump
154                       perl -MOpcode=opdump -e 'opdump Eval'
155

Manipulating Opsets

157       Opsets may be manipulated using the perl bit vector operators & (and),
158       | (or), ^ (xor) and ~ (negate/invert).
159
160       However you should never rely on the numerical position of any opcode
161       within the opset. In other words both sides of a bit vector operator
162       should be opsets returned from Opcode functions.
163
164       Also, since the number of opcodes in your current version of perl might
165       not be an exact multiple of eight, there may be unused bits in the last
166       byte of an upset. This should not cause any problems (Opcode functions
167       ignore those extra bits) but it does mean that using the ~ operator
168       will typically not produce the same 'physical' opset 'string' as the
169       invert_opset function.
170

TO DO (maybe)

172           $bool = opset_eq($opset1, $opset2)  true if opsets are logically
173                                               equivalent
174           $yes = opset_can($opset, @ops)      true if $opset has all @ops set
175
176           @diff = opset_diff($opset1, $opset2) => ('foo', '!bar', ...)
177

Predefined Opcode Tags

179       :base_core
180                null stub scalar pushmark wantarray const defined undef
181
182                rv2sv sassign
183
184                rv2av aassign aelem aelemfast aelemfast_lex aslice kvaslice
185                av2arylen
186
187                rv2hv helem hslice kvhslice each values keys exists delete
188                aeach akeys avalues multideref argelem argdefelem argcheck
189
190                preinc i_preinc predec i_predec postinc i_postinc
191                postdec i_postdec int hex oct abs pow multiply i_multiply
192                divide i_divide modulo i_modulo add i_add subtract i_subtract
193
194                left_shift right_shift bit_and bit_xor bit_or nbit_and
195                nbit_xor nbit_or sbit_and sbit_xor sbit_or negate i_negate not
196                complement ncomplement scomplement
197
198                lt i_lt gt i_gt le i_le ge i_ge eq i_eq ne i_ne ncmp i_ncmp
199                slt sgt sle sge seq sne scmp
200
201                substr vec stringify study pos length index rindex ord chr
202
203                ucfirst lcfirst uc lc fc quotemeta trans transr chop schop
204                chomp schomp
205
206                match split qr
207
208                list lslice splice push pop shift unshift reverse
209
210                cond_expr flip flop andassign orassign dorassign and or dor xor
211
212                warn die lineseq nextstate scope enter leave
213
214                rv2cv anoncode prototype coreargs avhvswitch anonconst
215
216                entersub leavesub leavesublv return method method_named
217                method_super method_redir method_redir_super
218                 -- XXX loops via recursion?
219
220                leaveeval -- needed for Safe to operate, is safe
221                             without entereval
222
223       :base_mem
224            These memory related ops are not included in :base_core because
225            they can easily be used to implement a resource attack (e.g.,
226            consume all available memory).
227
228                concat multiconcat repeat join range
229
230                anonlist anonhash
231
232            Note that despite the existence of this optag a memory resource
233            attack may still be possible using only :base_core ops.
234
235            Disabling these ops is a very heavy handed way to attempt to
236            prevent a memory resource attack. It's probable that a specific
237            memory limit mechanism will be added to perl in the near future.
238
239       :base_loop
240            These loop ops are not included in :base_core because they can
241            easily be used to implement a resource attack (e.g., consume all
242            available CPU time).
243
244                grepstart grepwhile
245                mapstart mapwhile
246                enteriter iter
247                enterloop leaveloop unstack
248                last next redo
249                goto
250
251       :base_io
252            These ops enable filehandle (rather than filename) based input and
253            output. These are safe on the assumption that only pre-existing
254            filehandles are available for use.  Usually, to create new
255            filehandles other ops such as open would need to be enabled, if
256            you don't take into account the magical open of ARGV.
257
258                readline rcatline getc read
259
260                formline enterwrite leavewrite
261
262                print say sysread syswrite send recv
263
264                eof tell seek sysseek
265
266                readdir telldir seekdir rewinddir
267
268       :base_orig
269            These are a hotchpotch of opcodes still waiting to be considered
270
271                gvsv gv gelem
272
273                padsv padav padhv padcv padany padrange introcv clonecv
274
275                once
276
277                rv2gv refgen srefgen ref refassign lvref lvrefslice lvavref
278
279                bless -- could be used to change ownership of objects
280                         (reblessing)
281
282                 regcmaybe regcreset regcomp subst substcont
283
284                sprintf prtf -- can core dump
285
286                crypt
287
288                tie untie
289
290                dbmopen dbmclose
291                sselect select
292                pipe_op sockpair
293
294                getppid getpgrp setpgrp getpriority setpriority
295                localtime gmtime
296
297                entertry leavetry -- can be used to 'hide' fatal errors
298
299                entergiven leavegiven
300                enterwhen leavewhen
301                break continue
302                smartmatch
303
304                custom -- where should this go
305
306       :base_math
307            These ops are not included in :base_core because of the risk of
308            them being used to generate floating point exceptions (which would
309            have to be caught using a $SIG{FPE} handler).
310
311                atan2 sin cos exp log sqrt
312
313            These ops are not included in :base_core because they have an
314            effect beyond the scope of the compartment.
315
316                rand srand
317
318       :base_thread
319            These ops are related to multi-threading.
320
321                lock
322
323       :default
324            A handy tag name for a reasonable default set of ops.  (The
325            current ops allowed are unstable while development continues. It
326            will change.)
327
328                :base_core :base_mem :base_loop :base_orig :base_thread
329
330            This list used to contain :base_io prior to Opcode 1.07.
331
332            If safety matters to you (and why else would you be using the
333            Opcode module?)  then you should not rely on the definition of
334            this, or indeed any other, optag!
335
336       :filesys_read
337                stat lstat readlink
338
339                ftatime ftblk ftchr ftctime ftdir fteexec fteowned
340                fteread ftewrite ftfile ftis ftlink ftmtime ftpipe
341                ftrexec ftrowned ftrread ftsgid ftsize ftsock ftsuid
342                fttty ftzero ftrwrite ftsvtx
343
344                fttext ftbinary
345
346                fileno
347
348       :sys_db
349                ghbyname ghbyaddr ghostent shostent ehostent      -- hosts
350                gnbyname gnbyaddr gnetent snetent enetent         -- networks
351                gpbyname gpbynumber gprotoent sprotoent eprotoent -- protocols
352                gsbyname gsbyport gservent sservent eservent      -- services
353
354                gpwnam gpwuid gpwent spwent epwent getlogin       -- users
355                ggrnam ggrgid ggrent sgrent egrent                -- groups
356
357       :browse
358            A handy tag name for a reasonable default set of ops beyond the
359            :default optag.  Like :default (and indeed all the other optags)
360            its current definition is unstable while development continues. It
361            will change.
362
363            The :browse tag represents the next step beyond :default. It it a
364            superset of the :default ops and adds :filesys_read the :sys_db.
365            The intent being that scripts can access more (possibly sensitive)
366            information about your system but not be able to change it.
367
368                :default :filesys_read :sys_db
369
370       :filesys_open
371                sysopen open close
372                umask binmode
373
374                open_dir closedir -- other dir ops are in :base_io
375
376       :filesys_write
377                link unlink rename symlink truncate
378
379                mkdir rmdir
380
381                utime chmod chown
382
383                fcntl -- not strictly filesys related, but possibly as
384                         dangerous?
385
386       :subprocess
387                backtick system
388
389                fork
390
391                wait waitpid
392
393                glob -- access to Cshell via <`rm *`>
394
395       :ownprocess
396                exec exit kill
397
398                time tms -- could be used for timing attacks (paranoid?)
399
400       :others
401            This tag holds groups of assorted specialist opcodes that don't
402            warrant having optags defined for them.
403
404            SystemV Interprocess Communications:
405
406                msgctl msgget msgrcv msgsnd
407
408                semctl semget semop
409
410                shmctl shmget shmread shmwrite
411
412       :load
413            This tag holds opcodes related to loading modules and getting
414            information about calling environment and args.
415
416                require dofile
417                caller runcv
418
419       :still_to_be_decided
420                chdir
421                flock ioctl
422
423                socket getpeername ssockopt
424                bind connect listen accept shutdown gsockopt getsockname
425
426                sleep alarm -- changes global timer state and signal handling
427                sort -- assorted problems including core dumps
428                tied -- can be used to access object implementing a tie
429                pack unpack -- can be used to create/use memory pointers
430
431                hintseval -- constant op holding eval hints
432
433                entereval -- can be used to hide code from initial compile
434
435                reset
436
437                dbstate -- perl -d version of nextstate(ment) opcode
438
439       :dangerous
440            This tag is simply a bucket for opcodes that are unlikely to be
441            used via a tag name but need to be tagged for completeness and
442            documentation.
443
444                syscall dump chroot
445

SEE ALSO

447       ops -- perl pragma interface to Opcode module.
448
449       Safe -- Opcode and namespace limited execution compartments
450

AUTHORS

452       Originally designed and implemented by Malcolm Beattie,
453       mbeattie@sable.ox.ac.uk as part of Safe version 1.
454
455       Split out from Safe module version 1, named opcode tags and other
456       changes added by Tim Bunce.
457
458
459
460perl v5.28.2                      2018-11-01                       Opcode(3pm)
Impressum