1Opcode(3pm) Perl Programmers Reference Guide Opcode(3pm)
2
6 Opcode - Disable named opcodes when compiling perl code
7
9 use Opcode;
10
12 Perl code is always compiled into an internal format before execution.
13 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 By default no opmask is in effect and any code can be compiled.
20 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
27 The Opcode module is not usually used directly. See the ops pragma and
28 Safe modules for more typical uses.
29
31 The Opcode module does not implement an effective sandbox for
32 evaluating untrusted code with the perl interpreter.
33 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 The authors make no warranty, implied or otherwise, about the
39 suitability of this software for safety or security purposes.
40 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 Your mileage will vary. If in any doubt do not use it.
46
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 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 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 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 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 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 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 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 Wherever a list of operators can be given you can use one or
85 more opsets. See also Manipulating Opsets below.
86
88 The Opcode package contains functions for manipulating operator names
89 tags and sets. All are available for export by the package.
90 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 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 opset (OP, ...)
98 Returns an opset containing the listed operators.
99 opset_to_ops (OPSET)
101 Returns a list of operator names corresponding to those
102 operators in the set.
103 opset_to_hex (OPSET)
105 Returns a string representation of an opset. Can be handy for
106 debugging.
107 full_opset
109 Returns an opset which includes all operators.
110 empty_opset
112 Returns an opset which contains no operators.
113 invert_opset (OPSET)
115 Returns an opset which is the inverse set of the one supplied.
116 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 Most of the other Opcode functions call verify_opset
124 automatically and will croak if given an invalid opset.
125 define_optag (OPTAG, OPSET)
127 Define OPTAG as a symbolic name for OPSET. Optag names always
128 start with a colon ":".
129 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 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 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 opmask Returns an opset corresponding to the current opmask.
148 opdesc (OP, ...)
150 This takes a list of operator names and returns the
151 corresponding list of operator descriptions.
152 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 It's designed to be used as a handy command line utility:
159 perl -MOpcode=opdump -e opdump
161 perl -MOpcode=opdump -e 'opdump Eval'
162
164 Opsets may be manipulated using the perl bit vector operators & (and),
165 | (or), ^ (xor) and ~ (negate/invert).
166 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 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
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 @diff = opset_diff($opset1, $opset2) => ('foo', '!bar', ...)
184
186 :base_core
187 null stub scalar pushmark wantarray const defined undef
188 rv2sv sassign padsv_store
190 rv2av aassign aelem aelemfast aelemfast_lex aslice kvaslice
192 av2arylen aelemfastlex_store
193 rv2hv helem hslice kvhslice each values keys exists delete
195 aeach akeys avalues multideref argelem argdefelem argcheck
196 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 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 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 substr vec stringify study pos length index rindex ord chr
210 ucfirst lcfirst uc lc fc quotemeta trans transr chop schop
212 chomp schomp
213 match split qr
215 list lslice splice push pop shift unshift reverse
217 cond_expr flip flop andassign orassign dorassign and or dor xor
219 helemexistsor
220 warn die lineseq nextstate scope enter leave
222 rv2cv anoncode prototype coreargs avhvswitch anonconst
224 emptyavhv
225 entersub leavesub leavesublv return method method_named
227 method_super method_redir method_redir_super
228 -- XXX loops via recursion?
229 cmpchain_and cmpchain_dup
231 is_bool
233 is_weak weaken unweaken
234 leaveeval -- needed for Safe to operate, is safe
236 without entereval
237 methstart initfield
239 :base_mem
241 These memory related ops are not included in :base_core because
242 they can easily be used to implement a resource attack (e.g.,
243 consume all available memory).
244 concat multiconcat repeat join range
246 anonlist anonhash
248 Note that despite the existence of this optag a memory resource
250 attack may still be possible using only :base_core ops.
251 Disabling these ops is a very heavy handed way to attempt to
253 prevent a memory resource attack. It's probable that a specific
254 memory limit mechanism will be added to perl in the near future.
255 :base_loop
257 These loop ops are not included in :base_core because they can
258 easily be used to implement a resource attack (e.g., consume all
259 available CPU time).
260 grepstart grepwhile
262 mapstart mapwhile
263 enteriter iter
264 enterloop leaveloop unstack
265 last next redo
266 goto
267 :base_io
269 These ops enable filehandle (rather than filename) based input and
270 output. These are safe on the assumption that only pre-existing
271 filehandles are available for use. Usually, to create new
272 filehandles other ops such as open would need to be enabled, if
273 you don't take into account the magical open of ARGV.
274 readline rcatline getc read
276 formline enterwrite leavewrite
278 print say sysread syswrite send recv
280 eof tell seek sysseek
282 readdir telldir seekdir rewinddir
284 :base_orig
286 These are a hotchpotch of opcodes still waiting to be considered
287 gvsv gv gelem
289 padsv padav padhv padcv padany padrange introcv clonecv
291 once
293 rv2gv refgen srefgen ref refassign lvref lvrefslice lvavref
295 blessed refaddr reftype
296 bless -- could be used to change ownership of objects
298 (reblessing)
299 regcmaybe regcreset regcomp subst substcont
301 sprintf prtf -- can core dump
303 crypt
305 tie untie
307 dbmopen dbmclose
309 sselect select
310 pipe_op sockpair
311 getppid getpgrp setpgrp getpriority setpriority
313 localtime gmtime
314 entertry leavetry -- can be used to 'hide' fatal errors
316 entertrycatch poptry catch leavetrycatch -- similar
317 entergiven leavegiven
319 enterwhen leavewhen
320 break continue
321 smartmatch
322 pushdefer
324 custom -- where should this go
326 ceil floor
328 is_tainted
330 :base_math
332 These ops are not included in :base_core because of the risk of
333 them being used to generate floating point exceptions (which would
334 have to be caught using a $SIG{FPE} handler).
335 atan2 sin cos exp log sqrt
337 These ops are not included in :base_core because they have an
339 effect beyond the scope of the compartment.
340 rand srand
342 :base_thread
344 These ops are related to multi-threading.
345 lock
347 :default
349 A handy tag name for a reasonable default set of ops. (The
350 current ops allowed are unstable while development continues. It
351 will change.)
352 :base_core :base_mem :base_loop :base_orig :base_thread
354 This list used to contain :base_io prior to Opcode 1.07.
356 If safety matters to you (and why else would you be using the
358 Opcode module?) then you should not rely on the definition of
359 this, or indeed any other, optag!
360 :filesys_read
362 stat lstat readlink
363 ftatime ftblk ftchr ftctime ftdir fteexec fteowned
365 fteread ftewrite ftfile ftis ftlink ftmtime ftpipe
366 ftrexec ftrowned ftrread ftsgid ftsize ftsock ftsuid
367 fttty ftzero ftrwrite ftsvtx
368 fttext ftbinary
370 fileno
372 :sys_db
374 ghbyname ghbyaddr ghostent shostent ehostent -- hosts
375 gnbyname gnbyaddr gnetent snetent enetent -- networks
376 gpbyname gpbynumber gprotoent sprotoent eprotoent -- protocols
377 gsbyname gsbyport gservent sservent eservent -- services
378 gpwnam gpwuid gpwent spwent epwent getlogin -- users
380 ggrnam ggrgid ggrent sgrent egrent -- groups
381 :browse
383 A handy tag name for a reasonable default set of ops beyond the
384 :default optag. Like :default (and indeed all the other optags)
385 its current definition is unstable while development continues. It
386 will change.
387 The :browse tag represents the next step beyond :default. It is a
389 superset of the :default ops and adds :filesys_read the :sys_db.
390 The intent being that scripts can access more (possibly sensitive)
391 information about your system but not be able to change it.
392 :default :filesys_read :sys_db
394 :filesys_open
396 sysopen open close
397 umask binmode
398 open_dir closedir -- other dir ops are in :base_io
400 :filesys_write
402 link unlink rename symlink truncate
403 mkdir rmdir
405 utime chmod chown
407 fcntl -- not strictly filesys related, but possibly as
409 dangerous?
410 :subprocess
412 backtick system
413 fork
415 wait waitpid
417 glob -- access to Cshell via <`rm *`>
419 :ownprocess
421 exec exit kill
422 time tms -- could be used for timing attacks (paranoid?)
424 :others
426 This tag holds groups of assorted specialist opcodes that don't
427 warrant having optags defined for them.
428 SystemV Interprocess Communications:
430 msgctl msgget msgrcv msgsnd
432 semctl semget semop
434 shmctl shmget shmread shmwrite
436 :load
438 This tag holds opcodes related to loading modules and getting
439 information about calling environment and args.
440 require dofile
442 caller runcv
443 :still_to_be_decided
445 chdir
446 flock ioctl
447 socket getpeername ssockopt
449 bind connect listen accept shutdown gsockopt getsockname
450 sleep alarm -- changes global timer state and signal handling
452 sort -- assorted problems including core dumps
453 tied -- can be used to access object implementing a tie
454 pack unpack -- can be used to create/use memory pointers
455 hintseval -- constant op holding eval hints
457 entereval -- can be used to hide code from initial compile
459 reset
461 dbstate -- perl -d version of nextstate(ment) opcode
463 :dangerous
465 This tag is simply a bucket for opcodes that are unlikely to be
466 used via a tag name but need to be tagged for completeness and
467 documentation.
468 syscall dump chroot
470
472 ops -- perl pragma interface to Opcode module.
473 Safe -- Opcode and namespace limited execution compartments
475
477 Originally designed and implemented by Malcolm Beattie,
478 mbeattie@sable.ox.ac.uk as part of Safe version 1.
479 Split out from Safe module version 1, named opcode tags and other
481 changes added by Tim Bunce.
482perl v5.38.2 2023-11-30 Opcode(3pm)