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 authors make no warranty, implied or otherwise, about the
32 suitability of this software for safety or security purposes.
33 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 Your mileage will vary. If in any doubt do not use it.
39
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 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 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 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 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 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 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 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 Wherever a list of operators can be given you can use one or
78 more opsets. See also Manipulating Opsets below.
79
81 The Opcode package contains functions for manipulating operator names
82 tags and sets. All are available for export by the package.
83 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 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 opset (OP, ...)
91 Returns an opset containing the listed operators.
92 opset_to_ops (OPSET)
94 Returns a list of operator names corresponding to those
95 operators in the set.
96 opset_to_hex (OPSET)
98 Returns a string representation of an opset. Can be handy for
99 debugging.
100 full_opset
102 Returns an opset which includes all operators.
103 empty_opset
105 Returns an opset which contains no operators.
106 invert_opset (OPSET)
108 Returns an opset which is the inverse set of the one supplied.
109 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 Most of the other Opcode functions call verify_opset
117 automatically and will croak if given an invalid opset.
118 define_optag (OPTAG, OPSET)
120 Define OPTAG as a symbolic name for OPSET. Optag names always
121 start with a colon ":".
122 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 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 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 opmask Returns an opset corresponding to the current opmask.
141 opdesc (OP, ...)
143 This takes a list of operator names and returns the
144 corresponding list of operator descriptions.
145 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 It's designed to be used as a handy command line utility:
152 perl -MOpcode=opdump -e opdump
154 perl -MOpcode=opdump -e 'opdump Eval'
155
157 Opsets may be manipulated using the perl bit vector operators & (and),
158 | (or), ^ (xor) and ~ (negate/invert).
159 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 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
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 @diff = opset_diff($opset1, $opset2) => ('foo', '!bar', ...)
177
179 :base_core
180 null stub scalar pushmark wantarray const defined undef
181 rv2sv sassign
183 rv2av aassign aelem aelemfast aelemfast_lex aslice kvaslice
185 av2arylen
186 rv2hv helem hslice kvhslice each values keys exists delete
188 aeach akeys avalues multideref argelem argdefelem argcheck
189 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 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 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 substr vec stringify study pos length index rindex ord chr
202 ucfirst lcfirst uc lc fc quotemeta trans transr chop schop
204 chomp schomp
205 match split qr
207 list lslice splice push pop shift unshift reverse
209 cond_expr flip flop andassign orassign dorassign and or dor xor
211 warn die lineseq nextstate scope enter leave
213 rv2cv anoncode prototype coreargs avhvswitch anonconst
215 entersub leavesub leavesublv return method method_named
217 method_super method_redir method_redir_super
218 -- XXX loops via recursion?
219 leaveeval -- needed for Safe to operate, is safe
221 without entereval
222 :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 concat multiconcat repeat join range
229 anonlist anonhash
231 Note that despite the existence of this optag a memory resource
233 attack may still be possible using only :base_core ops.
234 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 :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 grepstart grepwhile
245 mapstart mapwhile
246 enteriter iter
247 enterloop leaveloop unstack
248 last next redo
249 goto
250 :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 readline rcatline getc read
259 formline enterwrite leavewrite
261 print say sysread syswrite send recv
263 eof tell seek sysseek
265 readdir telldir seekdir rewinddir
267 :base_orig
269 These are a hotchpotch of opcodes still waiting to be considered
270 gvsv gv gelem
272 padsv padav padhv padcv padany padrange introcv clonecv
274 once
276 rv2gv refgen srefgen ref refassign lvref lvrefslice lvavref
278 bless -- could be used to change ownership of objects
280 (reblessing)
281 regcmaybe regcreset regcomp subst substcont
283 sprintf prtf -- can core dump
285 crypt
287 tie untie
289 dbmopen dbmclose
291 sselect select
292 pipe_op sockpair
293 getppid getpgrp setpgrp getpriority setpriority
295 localtime gmtime
296 entertry leavetry -- can be used to 'hide' fatal errors
298 entergiven leavegiven
300 enterwhen leavewhen
301 break continue
302 smartmatch
303 custom -- where should this go
305 :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 atan2 sin cos exp log sqrt
312 These ops are not included in :base_core because they have an
314 effect beyond the scope of the compartment.
315 rand srand
317 :base_thread
319 These ops are related to multi-threading.
320 lock
322 :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 :base_core :base_mem :base_loop :base_orig :base_thread
329 This list used to contain :base_io prior to Opcode 1.07.
331 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 :filesys_read
337 stat lstat readlink
338 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 fttext ftbinary
345 fileno
347 :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 gpwnam gpwuid gpwent spwent epwent getlogin -- users
355 ggrnam ggrgid ggrent sgrent egrent -- groups
356 :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 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 :default :filesys_read :sys_db
369 :filesys_open
371 sysopen open close
372 umask binmode
373 open_dir closedir -- other dir ops are in :base_io
375 :filesys_write
377 link unlink rename symlink truncate
378 mkdir rmdir
380 utime chmod chown
382 fcntl -- not strictly filesys related, but possibly as
384 dangerous?
385 :subprocess
387 backtick system
388 fork
390 wait waitpid
392 glob -- access to Cshell via <`rm *`>
394 :ownprocess
396 exec exit kill
397 time tms -- could be used for timing attacks (paranoid?)
399 :others
401 This tag holds groups of assorted specialist opcodes that don't
402 warrant having optags defined for them.
403 SystemV Interprocess Communications:
405 msgctl msgget msgrcv msgsnd
407 semctl semget semop
409 shmctl shmget shmread shmwrite
411 :load
413 This tag holds opcodes related to loading modules and getting
414 information about calling environment and args.
415 require dofile
417 caller runcv
418 :still_to_be_decided
420 chdir
421 flock ioctl
422 socket getpeername ssockopt
424 bind connect listen accept shutdown gsockopt getsockname
425 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 hintseval -- constant op holding eval hints
432 entereval -- can be used to hide code from initial compile
434 reset
436 dbstate -- perl -d version of nextstate(ment) opcode
438 :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 syscall dump chroot
445
447 ops -- perl pragma interface to Opcode module.
448 Safe -- Opcode and namespace limited execution compartments
450
452 Originally designed and implemented by Malcolm Beattie,
453 mbeattie@sable.ox.ac.uk as part of Safe version 1.
454 Split out from Safe module version 1, named opcode tags and other
456 changes added by Tim Bunce.
457perl v5.30.2 2020-03-27 Opcode(3pm)