X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/5486870fe7f0fd0e99bf9619d5fd857a5b972014..1bc149051a78b31f52161e3c6746033f2b39147a:/intrpvar.h diff --git a/intrpvar.h b/intrpvar.h index fbbe64f..4af88f6 100644 --- a/intrpvar.h +++ b/intrpvar.h @@ -1,8 +1,21 @@ -/***********************************************/ -/* Global only to current interpreter instance */ -/***********************************************/ +/* intrpvar.h + * + * Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, + * 2006, 2007, 2008 by Larry Wall and others + * + * You may distribute under the terms of either the GNU General Public + * License or the Artistic License, as specified in the README file. + * + */ -/* Don't forget to re-run embed.pl to propagate changes! */ +/* +=head1 Per-Interpreter Variables +*/ + +/* These variables are per-interpreter in threaded/multiplicity builds, + * global otherwise. + + * Don't forget to re-run embed.pl to propagate changes! */ /* New variables must be added to the very end for binary compatibility. * XSUB.h provides wrapper functions via perlapi.h that make this @@ -14,16 +27,192 @@ * generated when built with or without MULTIPLICITY. It is also used * to generate the appropriate export list for win32. * - * When building without MULTIPLICITY, these variables will be truly global. */ + * When building without MULTIPLICITY, these variables will be truly global. + * + * Important ones in the first cache line (if alignment is done right) */ + +PERLVAR(Istack_sp, SV **) /* top of the stack */ +#ifdef OP_IN_REGISTER +PERLVAR(Iopsave, OP *) +#else +PERLVAR(Iop, OP *) /* currently executing op */ +#endif +PERLVAR(Icurpad, SV **) /* active pad (lexicals+tmps) */ + +PERLVAR(Istack_base, SV **) +PERLVAR(Istack_max, SV **) + +PERLVAR(Iscopestack, I32 *) /* scopes we've ENTERed */ +/* name of the scopes we've ENTERed. Only used with -DDEBUGGING, but needs to be + present always, as -DDEUBGGING must be binary compatible with non. */ +PERLVARI(Iscopestack_name, const char * *, NULL) +PERLVAR(Iscopestack_ix, I32) +PERLVAR(Iscopestack_max,I32) + +PERLVAR(Isavestack, ANY *) /* items that need to be restored when + LEAVEing scopes we've ENTERed */ +PERLVAR(Isavestack_ix, I32) +PERLVAR(Isavestack_max, I32) + +PERLVAR(Itmps_stack, SV **) /* mortals we've made */ +PERLVARI(Itmps_ix, I32, -1) +PERLVARI(Itmps_floor, I32, -1) +PERLVAR(Itmps_max, I32) +PERLVAR(Imodcount, I32) /* how much mod()ification in + assignment? */ + +PERLVAR(Imarkstack, I32 *) /* stack_sp locations we're + remembering */ +PERLVAR(Imarkstack_ptr, I32 *) +PERLVAR(Imarkstack_max, I32 *) + +PERLVAR(ISv, SV *) /* used to hold temporary values */ +PERLVAR(IXpv, XPV *) /* used to hold temporary values */ + +/* +=for apidoc Amn|STRLEN|PL_na + +A convenience variable which is typically used with C when one +doesn't care about the length of the string. It is usually more efficient +to either declare a local variable and use that instead or to use the +C macro. + +=cut +*/ + +PERLVAR(Ina, STRLEN) /* for use in SvPV when length is + Not Applicable */ + +/* stat stuff */ +PERLVAR(Istatbuf, Stat_t) +PERLVAR(Istatcache, Stat_t) /* _ */ +PERLVAR(Istatgv, GV *) +PERLVARI(Istatname, SV *, NULL) + +#ifdef HAS_TIMES +PERLVAR(Itimesbuf, struct tms) +#endif + +/* Fields used by magic variables such as $@, $/ and so on */ +PERLVAR(Icurpm, PMOP *) /* what to do \ interps in REs from */ + +/* +=for apidoc mn|SV*|PL_rs + +The input record separator - C<$/> in Perl space. + +=for apidoc mn|GV*|PL_last_in_gv + +The GV which was last used for a filehandle input operation. (C<< >>) + +=for apidoc mn|GV*|PL_ofsgv + +The glob containing the output field separator - C<*,> in Perl space. + +=cut +*/ + +PERLVAR(Irs, SV *) /* input record separator $/ */ +PERLVAR(Ilast_in_gv, GV *) /* GV used in last */ +PERLVAR(Iofsgv, GV *) /* GV of output field separator *, */ +PERLVAR(Idefoutgv, GV *) /* default FH for output */ +PERLVARI(Ichopset, const char *, " \n-") /* $: */ +PERLVAR(Iformtarget, SV *) +PERLVAR(Ibodytarget, SV *) +PERLVAR(Itoptarget, SV *) + +/* Stashes */ +PERLVAR(Idefstash, HV *) /* main symbol table */ +PERLVAR(Icurstash, HV *) /* symbol table for current package */ +PERLVAR(Irestartop, OP *) /* propagating an error from croak? */ +PERLVAR(Irestartjmpenv, JMPENV *) /* target frame for longjmp in die */ +PERLVAR(Icurcop, COP *) +PERLVAR(Icurstack, AV *) /* THE STACK */ +PERLVAR(Icurstackinfo, PERL_SI *) /* current stack + context */ +PERLVAR(Imainstack, AV *) /* the stack when nothing funny is + happening */ -/* For historical reasons this file follows thrdvar.h into the interpeter - struct, and that file currently ends with 7 bytes of variables, so putting - one last byte here is good for alignment. */ +PERLVAR(Itop_env, JMPENV *) /* ptr to current sigjmp environment */ +PERLVAR(Istart_env, JMPENV) /* empty startup sigjmp environment */ +PERLVARI(Ierrors, SV *, NULL) /* outstanding queued errors */ + +/* statics "owned" by various functions */ +PERLVAR(Ihv_fetch_ent_mh, HE*) /* owned by hv_fetch_ent() */ + +PERLVAR(Ilastgotoprobe, OP*) /* from pp_ctl.c */ + +/* sort stuff */ +PERLVAR(Isortcop, OP *) /* user defined sort routine */ +PERLVAR(Isortstash, HV *) /* which is in some package or other */ +PERLVAR(Ifirstgv, GV *) /* $a */ +PERLVAR(Isecondgv, GV *) /* $b */ + +/* float buffer */ +PERLVAR(Iefloatbuf, char *) +PERLVAR(Iefloatsize, STRLEN) + +/* regex stuff */ + +PERLVAR(Iscreamfirst, I32 *) +PERLVAR(Iscreamnext, I32 *) +PERLVAR(Ilastscream, SV *) + +PERLVAR(Ireg_state, struct re_save_state) + +PERLVAR(Iregdummy, regnode) /* from regcomp.c */ + +PERLVARI(Idumpindent, U16, 4) /* number of blanks per dump + indentation level */ + + +PERLVAR(Iutf8locale, bool) /* utf8 locale detected */ +PERLVARI(Irehash_seed_set, bool, FALSE) /* 582 hash initialized? */ + +PERLVARA(Icolors,6, char *) /* from regcomp.c */ + +PERLVARI(Ipeepp, peep_t, MEMBER_TO_FPTR(Perl_peep)) + /* Pointer to peephole optimizer */ + +/* +=for apidoc Amn|Perl_ophook_t|PL_opfreehook + +When non-C, the function pointed by this variable will be called each time an OP is freed with the corresponding OP as the argument. +This allows extensions to free any extra attribute they have locally attached to an OP. +It is also assured to first fire for the parent OP and then for its kids. + +When you replace this variable, it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own. + +=cut +*/ + +PERLVARI(Iopfreehook, Perl_ophook_t, 0) /* op_free() hook */ + +PERLVARI(Imaxscream, I32, -1) +PERLVARI(Ireginterp_cnt,I32, 0) /* Whether "Regexp" was interpolated. */ +PERLVARI(Iwatchaddr, char **, 0) +PERLVAR(Iwatchok, char *) + +/* the currently active slab in a chain of slabs of regmatch states, + * and the currently active state within that slab */ + +PERLVARI(Iregmatch_slab, regmatch_slab *, NULL) +PERLVAR(Iregmatch_state, regmatch_state *) + +/* Put anything new that is pointer aligned here. */ + +PERLVAR(Idelaymagic, U16) /* ($<,$>) = ... */ +PERLVAR(Ilocalizing, U8) /* are we processing a local() list? */ +PERLVAR(Icolorset, bool) /* from regcomp.c */ +PERLVARI(Idirty, bool, FALSE) /* in the middle of tearing things + down? */ +PERLVAR(Iin_eval, U8) /* trap "fatal" errors? */ +PERLVAR(Itainted, bool) /* using variables controlled by $< */ /* This value may be set when embedding for full cleanup */ /* 0=none, 1=full, 2=full with checks */ -PERLVARI(Iperl_destruct_level, U8, 0) +/* mod_perl is special, and also assigns a meaning -1 */ +PERLVARI(Iperl_destruct_level, signed char, 0) PERLVAR(Iperldb, U32) @@ -43,18 +232,15 @@ PERLVAR(Ilocalpatches, const char * const *) PERLVARI(Isplitstr, const char *, " ") PERLVAR(Iminus_c, bool) -PERLVAR(Ipreprocess, bool) PERLVAR(Iminus_n, bool) PERLVAR(Iminus_p, bool) PERLVAR(Iminus_l, bool) PERLVAR(Iminus_a, bool) PERLVAR(Iminus_F, bool) PERLVAR(Idoswitches, bool) - PERLVAR(Iminus_E, bool) /* -=head1 Global Variables =for apidoc mn|bool|PL_dowarn @@ -71,6 +257,7 @@ PERLVAR(Iexit_flags, U8) /* was exit() unexpected, etc. */ PERLVAR(Isrand_called, bool) /* Part of internal state, but makes the 16th 1 byte variable in a row. */ PERLVAR(Itainting, bool) /* doing taint checks */ +/* Space for a U8 */ PERLVAR(Iinplace, char *) PERLVAR(Ie_script, SV *) @@ -88,10 +275,8 @@ PERLVAR(Istatusvalue_vms,U32) PERLVAR(Istatusvalue_posix,I32) #endif -#ifdef CSH -PERLVARI(Icshlen, I32, 0) -PERLVARI(Icshname, const char *, CSH) -#endif +PERLVARI(Isig_pending, int,0) /* Number if highest signal pending */ +PERLVAR(Ipsig_pend, int *) /* per-signal "count" of pending */ /* shortcuts to various I/O objects */ PERLVAR(Istdingv, GV *) @@ -102,8 +287,6 @@ PERLVAR(Iargvoutgv, GV *) PERLVAR(Iargvout_stack, AV *) /* shortcuts to regexp stuff */ -/* this one needs to be moved to thrdvar.h and accessed via - * find_threadsv() when USE_5005THREADS */ PERLVAR(Ireplgv, GV *) /* shortcuts to misc objects */ @@ -139,7 +322,6 @@ PERLVAR(IDBsub, GV *) PERLVAR(IDBsingle, SV *) PERLVAR(IDBtrace, SV *) PERLVAR(IDBsignal, SV *) -PERLVAR(Ilineary, AV *) /* lines of script for debugger */ PERLVAR(Idbargs, AV *) /* args to call listed by caller function */ /* symbol tables */ @@ -182,14 +364,19 @@ PERLVARI(Icurcopdb, COP *, NULL) PERLVAR(Ifilemode, int) /* so nextargv() can preserve mode */ PERLVAR(Ilastfd, int) /* what to preserve mode on */ PERLVAR(Ioldname, char *) /* what to preserve mode on */ -PERLVAR(IArgv, char **) /* stuff to free from do_aexec, vfork safe */ +PERLVAR(IArgv, const char **) /* stuff to free from do_aexec, vfork safe */ PERLVAR(ICmd, char *) /* stuff to free from do_aexec, vfork safe */ +/* Elements in this array have ';' appended and are injected as a single line + into the tokeniser. You can't put any (literal) newlines into any program + you stuff in into this array, as the point where it's injected is expecting + a single physical line. */ PERLVAR(Ipreambleav, AV *) PERLVAR(Imess_sv, SV *) PERLVAR(Iors_sv, SV *) /* output record separator $\ */ /* statics moved here for shared library purposes */ PERLVARI(Igensym, I32, 0) /* next symbol for getsym() to define */ -PERLVAR(Iin_my, U16) /* we're compiling a "my" (or "our") declaration */ +PERLVARI(Icv_has_eval, bool, FALSE) /* PL_compcv includes an entereval or similar */ +PERLVAR(Itaint_warn, bool) /* taint warns instead of dying */ PERLVARI(Ilaststype, U16, OP_STAT) PERLVARI(Ilaststatval, int, -1) @@ -262,8 +449,6 @@ PERLVARI(Imaxo, int, MAXO) /* maximum number of ops */ PERLVARI(Irunops, runops_proc_t, MEMBER_TO_FPTR(RUNOPS_DEFAULT)) -PERLVARA(Itokenbuf,256, char) - /* =for apidoc Amn|SV|PL_sv_undef This is the C SV. Always refer to this as C<&PL_sv_undef>. @@ -283,12 +468,6 @@ PERLVAR(Isv_undef, SV) PERLVAR(Isv_no, SV) PERLVAR(Isv_yes, SV) -PERLVAR(Ierror_count, U8) /* how many errors so far, max 10 */ -PERLVARI(Icv_has_eval, bool, FALSE) /* PL_compcv includes an entereval or similar */ -/* Space for two more U8 here without increasing the structure size */ - -PERLVAR(Imulti_end, I32) /* last line of multi-line string */ - PERLVAR(Isubname, SV *) /* name of current subroutine */ PERLVAR(Isubline, I32) /* line this subroutine began on */ @@ -298,14 +477,14 @@ PERLVAR(Imax_intro_pending, I32) /* end of vars to introduce */ PERLVAR(Ipadix, I32) /* max used index in current "register" pad */ PERLVAR(Ipadix_floor, I32) /* how low may inner block reset padix */ -PERLVAR(Ipad_reset_pending, I32) /* reset pad on next attempted alloc */ - -PERLVAR(Iin_my_stash, HV *) /* declared class of this "my" declaration */ PERLVAR(Ihints, U32) /* pragma-tic compile-time flags */ PERLVAR(Idebug, VOL U32) /* flags given to -D switch */ +/* Perl_Ibreakable_sub_generation_ptr was too long for VMS, hence "gen" */ +PERLVARI(Ibreakable_sub_gen, U32, 0) + PERLVARI(Iamagic_generation, long, 0) #ifdef USE_LOCALE_COLLATE @@ -318,11 +497,14 @@ PERLVARI(Icollation_standard, bool, TRUE) #endif /* USE_LOCALE_COLLATE */ -#ifdef PERL_UTF8_CACHE_ASSERT -PERLVARI(Iutf8cache, I8, -1) /* Is the utf8 caching code enabled? */ +#if defined (PERL_UTF8_CACHE_ASSERT) || defined (DEBUGGING) +# define PERL___I -1 #else -PERLVARI(Iutf8cache, I8, 1) /* Is the utf8 caching code enabled? */ +# define PERL___I 1 #endif +PERLVARI(Iutf8cache, I8, PERL___I) /* Is the utf8 caching code enabled? */ +#undef PERL___I + #ifdef USE_LOCALE_NUMERIC @@ -335,10 +517,12 @@ PERLVAR(Inumeric_name, char *) /* Name of current numeric locale */ /* utf8 character classes */ PERLVAR(Iutf8_alnum, SV *) -PERLVAR(Iutf8_alnumc, SV *) PERLVAR(Iutf8_ascii, SV *) PERLVAR(Iutf8_alpha, SV *) PERLVAR(Iutf8_space, SV *) +PERLVAR(Iutf8_perl_space, SV *) +PERLVAR(Iutf8_perl_word, SV *) +PERLVAR(Iutf8_posix_digit, SV *) PERLVAR(Iutf8_cntrl, SV *) PERLVAR(Iutf8_graph, SV *) PERLVAR(Iutf8_digit, SV *) @@ -348,6 +532,16 @@ PERLVAR(Iutf8_print, SV *) PERLVAR(Iutf8_punct, SV *) PERLVAR(Iutf8_xdigit, SV *) PERLVAR(Iutf8_mark, SV *) +PERLVAR(Iutf8_X_begin, SV *) +PERLVAR(Iutf8_X_extend, SV *) +PERLVAR(Iutf8_X_prepend, SV *) +PERLVAR(Iutf8_X_non_hangul, SV *) +PERLVAR(Iutf8_X_L, SV *) +PERLVAR(Iutf8_X_LV, SV *) +PERLVAR(Iutf8_X_LVT, SV *) +PERLVAR(Iutf8_X_T, SV *) +PERLVAR(Iutf8_X_V, SV *) +PERLVAR(Iutf8_X_LV_LVT_V, SV *) PERLVAR(Iutf8_toupper, SV *) PERLVAR(Iutf8_totitle, SV *) PERLVAR(Iutf8_tolower, SV *) @@ -362,15 +556,20 @@ PERLVAR(Ilast_swash_klen, U8) /* Only needs to store 0-10 */ PERLVARI(Icryptseen, bool, FALSE) /* has fast crypt() been initialized? */ #endif +PERLVAR(Ipad_reset_pending, bool) /* reset pad on next attempted alloc */ + PERLVARI(Iglob_index, int, 0) PERLVAR(Iparser, yy_parser *) /* current parser state */ -PERLVAR(Ibitcount, char *) - +/* Array of signal handlers, indexed by signal number, through which the C + signal handler dispatches. */ PERLVAR(Ipsig_ptr, SV**) -PERLVAR(Ipsig_name, SV**) +/* Array of names of signals, indexed by signal number, for (re)use as the first + argument to a signal handler. Only one block of memory is allocated for + both psig_name and psig_ptr. */ +PERLVAR(Ipsig_name, SV**) #if defined(PERL_IMPLICIT_SYS) PERLVAR(IMem, struct IPerlMem*) @@ -389,14 +588,6 @@ PERLVARI(Ibeginav_save, AV*, NULL) /* save BEGIN{}s when compiling */ PERLVAR(Ibody_arenas, void*) /* pointer to list of body-arenas */ -PERLVAR(Ipsig_pend, int *) /* per-signal "count" of pending */ -PERLVARI(Isig_pending, int,0) /* Number if highest signal pending */ - - -PERLVAR(Itaint_warn, bool) /* taint warns instead of dying */ -PERLVAR(Iutf8locale, bool) /* utf8 locale detected */ -PERLVARI(Ihash_seed_set, bool, FALSE) /* Hash initialized? */ -PERLVARI(Irehash_seed_set, bool, FALSE) /* 582 hash initialized? */ #ifdef USE_LOCALE_NUMERIC @@ -405,22 +596,19 @@ PERLVAR(Inumeric_radix_sv, SV *) /* The radix separator if not '.' */ #endif #if defined(USE_ITHREADS) -PERLVAR(Iregex_pad, SV**) /* All regex objects */ -PERLVAR(Iregex_padav, AV*) /* All regex objects */ - +PERLVAR(Iregex_pad, SV**) /* Shortcut into the array of + regex_padav */ +PERLVAR(Iregex_padav, AV*) /* All regex objects, indexed via the + values in op_pmoffset of pmop. + Entry 0 is an SV whose PV is a + "packed" list of IVs listing + the now-free slots in the array */ #endif #ifdef USE_REENTRANT_API PERLVAR(Ireentrant_buffer, REENTR*) /* here we store the _r buffers */ #endif - -#ifdef PERL_MAD -PERLVARI(Imadskills, bool, FALSE) /* preserve all syntactic info */ - /* (MAD = Misc Attribute Decoration) */ -PERLVARI(Ixmlfp, PerlIO *,NULL) -#endif - PERLVAR(Icustom_op_names, HV*) /* Names of user defined ops */ PERLVAR(Icustom_op_descs, HV*) /* Descriptions of user defined ops */ @@ -434,12 +622,6 @@ PERLVARI(Iencoding, SV*, NULL) /* character encoding */ PERLVAR(Idebug_pad, struct perl_debug_pad) /* always needed because of the re extension */ -#ifdef PL_OP_SLAB_ALLOC -PERLVAR(IOpPtr,I32 **) -PERLVARI(IOpSpace,I32,0) -PERLVAR(IOpSlab,I32 *) -#endif - PERLVAR(Iutf8_idstart, SV *) PERLVAR(Iutf8_idcont, SV *) @@ -473,32 +655,24 @@ PERLVARI(Iunlockhook, share_proc_t, MEMBER_TO_FPTR(PERL_UNLOCK_HOOK)) PERLVARI(Ithreadhook, thrhook_proc_t, MEMBER_TO_FPTR(Perl_nothreadhook)) -/* Force inclusion of both runops options */ -PERLVARI(Irunops_std, runops_proc_t, MEMBER_TO_FPTR(Perl_runops_standard)) -PERLVARI(Irunops_dbg, runops_proc_t, MEMBER_TO_FPTR(Perl_runops_debug)) - -/* Stores the PPID */ -#ifdef THREADS_HAVE_PIDS -PERLVARI(Ippid, IV, 0) -#endif - PERLVARI(Ihash_seed, UV, 0) /* Hash initializer */ -PERLVAR(IDBassertion, SV *) - PERLVARI(Irehash_seed, UV, 0) /* 582 hash initializer */ -#ifdef DEBUG_LEAKING_SCALARS_FORK_DUMP -/* File descriptor to talk to the child which dumps scalars. */ -PERLVARI(Idumper_fd, int, -1) -#endif +PERLVARI(Iisarev, HV*, NULL) /* Reverse map of @ISA dependencies */ + +/* The last unconditional member of the interpreter structure when 5.10.0 was + released. The offset of the end of this is baked into a global variable in + any shared perl library which will allow a sanity test in future perl + releases. */ +#define PERL_LAST_5_10_0_INTERP_MEMBER Iisarev #ifdef PERL_IMPLICIT_CONTEXT PERLVARI(Imy_cxt_size, int, 0) /* size of PL_my_cxt_list */ PERLVARI(Imy_cxt_list, void **, NULL) /* per-module array of MY_CXT pointers */ -#ifdef PERL_GLOBAL_STRUCT_PRIVATE +# ifdef PERL_GLOBAL_STRUCT_PRIVATE PERLVARI(Imy_cxt_keys, const char **, NULL) /* per-module array of pointers to MY_CXT_KEY constants */ -#endif +# endif #endif #ifdef PERL_TRACK_MEMPOOL @@ -506,15 +680,48 @@ PERLVARI(Imy_cxt_keys, const char **, NULL) /* per-module array of pointers to M PERLVAR(Imemory_debug_header, struct perl_memory_debug_header) #endif +#ifdef DEBUG_LEAKING_SCALARS_FORK_DUMP +/* File descriptor to talk to the child which dumps scalars. */ +PERLVARI(Idumper_fd, int, -1) +#endif + +/* Stores the PPID */ +#ifdef THREADS_HAVE_PIDS +PERLVARI(Ippid, IV, 0) +#endif + +#ifdef PERL_MAD +PERLVARI(Imadskills, bool, FALSE) /* preserve all syntactic info */ + /* (MAD = Misc Attribute Decoration) */ +PERLVARI(Ixmlfp, PerlIO *,NULL) +#endif + +#ifdef PL_OP_SLAB_ALLOC +PERLVAR(IOpPtr,I32 **) +PERLVARI(IOpSpace,I32,0) +PERLVAR(IOpSlab,I32 *) +#endif + #ifdef PERL_DEBUG_READONLY_OPS PERLVARI(Islabs, I32**, NULL) /* Array of slabs that have been allocated */ PERLVARI(Islab_count, U32, 0) /* Size of the array */ #endif -PERLVARI(Iisarev, HV*, NULL) /* Reverse map of @ISA dependencies */ +/* Can shared object be destroyed */ +PERLVARI(Idestroyhook, destroyable_proc_t, MEMBER_TO_FPTR(Perl_sv_destroyable)) + +#ifdef DEBUG_LEAKING_SCALARS +PERLVARI(Isv_serial, U32, 0) /* SV serial number, used in sv.c */ +#endif + +/* Register of known Method Resolution Orders. + What this actually points to is an implementation detail (it may change to + a structure incorporating a reference count - use mro_get_from_name to + retrieve a C */ +PERLVAR(Iregistered_mros, HV *) -/* If you are adding a U8 or U16, see the 'Space' comments above on where - * there are gaps which currently will be structure padding. */ +/* If you are adding a U8 or U16, check to see if there are 'Space' comments + * above on where there are gaps which currently will be structure padding. */ /* Within a stable branch, new variables must be added to the very end, before * this comment, for binary compatibility (the offsets of the old members must