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 Opcode module does not implement an effective sandbox for
32       evaluating untrusted code with the perl interpreter.
33
34       Bugs in the perl interpreter that could be abused to bypass Opcode
35       restrictions are not treated as vulnerabilities. See perlsecpolicy for
36       additional information.
37
38       The authors make no warranty, implied or otherwise, about the
39       suitability of this software for safety or security purposes.
40
41       The authors shall not in any case be liable for special, incidental,
42       consequential, indirect or other similar damages arising from the use
43       of this software.
44
45       Your mileage will vary. If in any doubt do not use it.
46

Operator Names and Operator Lists

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

Opcode Functions

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

Manipulating Opsets

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

TO DO (maybe)

179           $bool = opset_eq($opset1, $opset2)  true if opsets are logically
180                                               equivalent
181           $yes = opset_can($opset, @ops)      true if $opset has all @ops set
182
183           @diff = opset_diff($opset1, $opset2) => ('foo', '!bar', ...)
184

Predefined Opcode Tags

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

SEE ALSO

466       ops -- perl pragma interface to Opcode module.
467
468       Safe -- Opcode and namespace limited execution compartments
469

AUTHORS

471       Originally designed and implemented by Malcolm Beattie,
472       mbeattie@sable.ox.ac.uk as part of Safe version 1.
473
474       Split out from Safe module version 1, named opcode tags and other
475       changes added by Tim Bunce.
476
477
478
479perl v5.36.3                      2023-11-30                       Opcode(3pm)
Impressum