js/src/jsdbgapi.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sw=4 et tw=78:
   3  *
   4  * ***** BEGIN LICENSE BLOCK *****
   5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   6  *
   7  * The contents of this file are subject to the Mozilla Public License Version
   8  * 1.1 (the "License"); you may not use this file except in compliance with
   9  * the License. You may obtain a copy of the License at
  10  * http://www.mozilla.org/MPL/
  11  *
  12  * Software distributed under the License is distributed on an "AS IS" basis,
  13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14  * for the specific language governing rights and limitations under the
  15  * License.
  16  *
  17  * The Original Code is Mozilla Communicator client code, released
  18  * March 31, 1998.
  19  *
  20  * The Initial Developer of the Original Code is
  21  * Netscape Communications Corporation.
  22  * Portions created by the Initial Developer are Copyright (C) 1998
  23  * the Initial Developer. All Rights Reserved.
  24  *
  25  * Contributor(s):
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #ifndef jsdbgapi_h___
  42 #define jsdbgapi_h___
  43 /*
  44  * JS debugger API.
  45  */
  46 #include "jsapi.h"
  47 #include "jsopcode.h"
  48 #include "jsprvtd.h"
  49
  50 JS_BEGIN_EXTERN_C
  51
  52 /*
  53  * Unexported library-private helper used to unpatch all traps in a script.
  54  * Returns script->code if script has no traps, else a JS_malloc'ed copy of
  55  * script->code which the caller must JS_free, or null on JS_malloc OOM.
  56  */
  57 extern jsbytecode *
  58 js_UntrapScriptCode(JSContext *cx, JSScript *script);
  59
  60 extern JS_PUBLIC_API(JSBool)
  61 JS_SetTrap(JSContext *cx, JSScript *script, jsbytecode *pc,
  62            JSTrapHandler handler, void *closure);
  63
  64 extern JS_PUBLIC_API(JSOp)
  65 JS_GetTrapOpcode(JSContext *cx, JSScript *script, jsbytecode *pc);
  66
  67 extern JS_PUBLIC_API(void)
  68 JS_ClearTrap(JSContext *cx, JSScript *script, jsbytecode *pc,
  69              JSTrapHandler *handlerp, void **closurep);
  70
  71 extern JS_PUBLIC_API(void)
  72 JS_ClearScriptTraps(JSContext *cx, JSScript *script);
  73
  74 extern JS_PUBLIC_API(void)
  75 JS_ClearAllTraps(JSContext *cx);
  76
  77 extern JS_PUBLIC_API(JSTrapStatus)
  78 JS_HandleTrap(JSContext *cx, JSScript *script, jsbytecode *pc, jsval *rval);
  79
  80 extern JS_PUBLIC_API(JSBool)
  81 JS_SetInterrupt(JSRuntime *rt, JSTrapHandler handler, void *closure);
  82
  83 extern JS_PUBLIC_API(JSBool)
  84 JS_ClearInterrupt(JSRuntime *rt, JSTrapHandler *handlerp, void **closurep);
  85
  86 /************************************************************************/
  87
  88 extern JS_PUBLIC_API(JSBool)
  89 JS_SetWatchPoint(JSContext *cx, JSObject *obj, jsval id,
  90                  JSWatchPointHandler handler, void *closure);
  91
  92 extern JS_PUBLIC_API(JSBool)
  93 JS_ClearWatchPoint(JSContext *cx, JSObject *obj, jsval id,
  94                    JSWatchPointHandler *handlerp, void **closurep);
  95
  96 extern JS_PUBLIC_API(JSBool)
  97 JS_ClearWatchPointsForObject(JSContext *cx, JSObject *obj);
  98
  99 extern JS_PUBLIC_API(JSBool)
 100 JS_ClearAllWatchPoints(JSContext *cx);
 101
 102 #ifdef JS_HAS_OBJ_WATCHPOINT
 103 /*
 104  * Hide these non-API function prototypes by testing whether the internal
 105  * header file "jsversion.h" has been included.
 106  */
 107 extern void
 108 js_TraceWatchPoints(JSTracer *trc, JSObject *obj);
 109
 110 extern void
 111 js_SweepWatchPoints(JSContext *cx);
 112
 113 extern JSScopeProperty *
 114 js_FindWatchPoint(JSRuntime *rt, JSScope *scope, jsid id);
 115
 116 /*
 117  * NB: callers outside of jsdbgapi.c must pass non-null scope.
 118  */
 119 extern JSPropertyOp
 120 js_GetWatchedSetter(JSRuntime *rt, JSScope *scope,
 121                     const JSScopeProperty *sprop);
 122
 123 extern JSBool
 124 js_watch_set(JSContext *cx, JSObject *obj, jsval id, jsval *vp);
 125
 126 extern JSBool
 127 js_watch_set_wrapper(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 128                      jsval *rval);
 129
 130 extern JSPropertyOp
 131 js_WrapWatchedSetter(JSContext *cx, jsid id, uintN attrs, JSPropertyOp setter);
 132
 133 #endif /* JS_HAS_OBJ_WATCHPOINT */
 134
 135 /************************************************************************/
 136
 137 extern JS_PUBLIC_API(uintN)
 138 JS_PCToLineNumber(JSContext *cx, JSScript *script, jsbytecode *pc);
 139
 140 extern JS_PUBLIC_API(jsbytecode *)
 141 JS_LineNumberToPC(JSContext *cx, JSScript *script, uintN lineno);
 142
 143 extern JS_PUBLIC_API(JSScript *)
 144 JS_GetFunctionScript(JSContext *cx, JSFunction *fun);
 145
 146 extern JS_PUBLIC_API(JSNative)
 147 JS_GetFunctionNative(JSContext *cx, JSFunction *fun);
 148
 149 extern JS_PUBLIC_API(JSFastNative)
 150 JS_GetFunctionFastNative(JSContext *cx, JSFunction *fun);
 151
 152 extern JS_PUBLIC_API(JSPrincipals *)
 153 JS_GetScriptPrincipals(JSContext *cx, JSScript *script);
 154
 155 /*
 156  * Stack Frame Iterator
 157  *
 158  * Used to iterate through the JS stack frames to extract
 159  * information from the frames.
 160  */
 161
 162 extern JS_PUBLIC_API(JSStackFrame *)
 163 JS_FrameIterator(JSContext *cx, JSStackFrame **iteratorp);
 164
 165 extern JS_PUBLIC_API(JSScript *)
 166 JS_GetFrameScript(JSContext *cx, JSStackFrame *fp);
 167
 168 extern JS_PUBLIC_API(jsbytecode *)
 169 JS_GetFramePC(JSContext *cx, JSStackFrame *fp);
 170
 171 /*
 172  * Get the closest scripted frame below fp.  If fp is null, start from cx->fp.
 173  */
 174 extern JS_PUBLIC_API(JSStackFrame *)
 175 JS_GetScriptedCaller(JSContext *cx, JSStackFrame *fp);
 176
 177 /*
 178  * Return a weak reference to fp's principals.  A null return does not denote
 179  * an error, it means there are no principals.
 180  */
 181 extern JS_PUBLIC_API(JSPrincipals *)
 182 JS_StackFramePrincipals(JSContext *cx, JSStackFrame *fp);
 183
 184 /*
 185  * This API is like JS_StackFramePrincipals(cx, caller), except that if
 186  * cx->runtime->findObjectPrincipals is non-null, it returns the weaker of
 187  * the caller's principals and the object principals of fp's callee function
 188  * object (fp->argv[-2]), which is eval, Function, or a similar eval-like
 189  * method.  The caller parameter should be JS_GetScriptedCaller(cx, fp).
 190  *
 191  * All eval-like methods must use JS_EvalFramePrincipals to acquire a weak
 192  * reference to the correct principals for the eval call to be secure, given
 193  * an embedding that calls JS_SetObjectPrincipalsFinder (see jsapi.h).
 194  */
 195 extern JS_PUBLIC_API(JSPrincipals *)
 196 JS_EvalFramePrincipals(JSContext *cx, JSStackFrame *fp, JSStackFrame *caller);
 197
 198 extern JS_PUBLIC_API(void *)
 199 JS_GetFrameAnnotation(JSContext *cx, JSStackFrame *fp);
 200
 201 extern JS_PUBLIC_API(void)
 202 JS_SetFrameAnnotation(JSContext *cx, JSStackFrame *fp, void *annotation);
 203
 204 extern JS_PUBLIC_API(void *)
 205 JS_GetFramePrincipalArray(JSContext *cx, JSStackFrame *fp);
 206
 207 extern JS_PUBLIC_API(JSBool)
 208 JS_IsNativeFrame(JSContext *cx, JSStackFrame *fp);
 209
 210 /* this is deprecated, use JS_GetFrameScopeChain instead */
 211 extern JS_PUBLIC_API(JSObject *)
 212 JS_GetFrameObject(JSContext *cx, JSStackFrame *fp);
 213
 214 extern JS_PUBLIC_API(JSObject *)
 215 JS_GetFrameScopeChain(JSContext *cx, JSStackFrame *fp);
 216
 217 extern JS_PUBLIC_API(JSObject *)
 218 JS_GetFrameCallObject(JSContext *cx, JSStackFrame *fp);
 219
 220 extern JS_PUBLIC_API(JSObject *)
 221 JS_GetFrameThis(JSContext *cx, JSStackFrame *fp);
 222
 223 extern JS_PUBLIC_API(JSFunction *)
 224 JS_GetFrameFunction(JSContext *cx, JSStackFrame *fp);
 225
 226 extern JS_PUBLIC_API(JSObject *)
 227 JS_GetFrameFunctionObject(JSContext *cx, JSStackFrame *fp);
 228
 229 /* XXXrginda Initially published with typo */
 230 #define JS_IsContructorFrame JS_IsConstructorFrame
 231 extern JS_PUBLIC_API(JSBool)
 232 JS_IsConstructorFrame(JSContext *cx, JSStackFrame *fp);
 233
 234 extern JS_PUBLIC_API(JSBool)
 235 JS_IsDebuggerFrame(JSContext *cx, JSStackFrame *fp);
 236
 237 extern JS_PUBLIC_API(jsval)
 238 JS_GetFrameReturnValue(JSContext *cx, JSStackFrame *fp);
 239
 240 extern JS_PUBLIC_API(void)
 241 JS_SetFrameReturnValue(JSContext *cx, JSStackFrame *fp, jsval rval);
 242
 243 /**
 244  * Return fp's callee function object (fp->callee) if it has one.
 245  */
 246 extern JS_PUBLIC_API(JSObject *)
 247 JS_GetFrameCalleeObject(JSContext *cx, JSStackFrame *fp);
 248
 249 /************************************************************************/
 250
 251 extern JS_PUBLIC_API(const char *)
 252 JS_GetScriptFilename(JSContext *cx, JSScript *script);
 253
 254 extern JS_PUBLIC_API(uintN)
 255 JS_GetScriptBaseLineNumber(JSContext *cx, JSScript *script);
 256
 257 extern JS_PUBLIC_API(uintN)
 258 JS_GetScriptLineExtent(JSContext *cx, JSScript *script);
 259
 260 extern JS_PUBLIC_API(JSVersion)
 261 JS_GetScriptVersion(JSContext *cx, JSScript *script);
 262
 263 /************************************************************************/
 264
 265 /*
 266  * Hook setters for script creation and destruction, see jsprvtd.h for the
 267  * typedefs.  These macros provide binary compatibility and newer, shorter
 268  * synonyms.
 269  */
 270 #define JS_SetNewScriptHook     JS_SetNewScriptHookProc
 271 #define JS_SetDestroyScriptHook JS_SetDestroyScriptHookProc
 272
 273 extern JS_PUBLIC_API(void)
 274 JS_SetNewScriptHook(JSRuntime *rt, JSNewScriptHook hook, void *callerdata);
 275
 276 extern JS_PUBLIC_API(void)
 277 JS_SetDestroyScriptHook(JSRuntime *rt, JSDestroyScriptHook hook,
 278                         void *callerdata);
 279
 280 /************************************************************************/
 281
 282 extern JS_PUBLIC_API(JSBool)
 283 JS_EvaluateUCInStackFrame(JSContext *cx, JSStackFrame *fp,
 284                           const jschar *chars, uintN length,
 285                           const char *filename, uintN lineno,
 286                           jsval *rval);
 287
 288 extern JS_PUBLIC_API(JSBool)
 289 JS_EvaluateInStackFrame(JSContext *cx, JSStackFrame *fp,
 290                         const char *bytes, uintN length,
 291                         const char *filename, uintN lineno,
 292                         jsval *rval);
 293
 294 /************************************************************************/
 295
 296 typedef struct JSPropertyDesc {
 297     jsval           id;         /* primary id, a string or int */
 298     jsval           value;      /* property value */
 299     uint8           flags;      /* flags, see below */
 300     uint8           spare;      /* unused */
 301     uint16          slot;       /* argument/variable slot */
 302     jsval           alias;      /* alias id if JSPD_ALIAS flag */
 303 } JSPropertyDesc;
 304
 305 #define JSPD_ENUMERATE  0x01    /* visible to for/in loop */
 306 #define JSPD_READONLY   0x02    /* assignment is error */
 307 #define JSPD_PERMANENT  0x04    /* property cannot be deleted */
 308 #define JSPD_ALIAS      0x08    /* property has an alias id */
 309 #define JSPD_ARGUMENT   0x10    /* argument to function */
 310 #define JSPD_VARIABLE   0x20    /* local variable in function */
 311 #define JSPD_EXCEPTION  0x40    /* exception occurred fetching the property, */
 312                                 /* value is exception */
 313 #define JSPD_ERROR      0x80    /* native getter returned JS_FALSE without */
 314                                 /* throwing an exception */
 315
 316 typedef struct JSPropertyDescArray {
 317     uint32          length;     /* number of elements in array */
 318     JSPropertyDesc  *array;     /* alloc'd by Get, freed by Put */
 319 } JSPropertyDescArray;
 320
 321 extern JS_PUBLIC_API(JSScopeProperty *)
 322 JS_PropertyIterator(JSObject *obj, JSScopeProperty **iteratorp);
 323
 324 extern JS_PUBLIC_API(JSBool)
 325 JS_GetPropertyDesc(JSContext *cx, JSObject *obj, JSScopeProperty *sprop,
 326                    JSPropertyDesc *pd);
 327
 328 extern JS_PUBLIC_API(JSBool)
 329 JS_GetPropertyDescArray(JSContext *cx, JSObject *obj, JSPropertyDescArray *pda);
 330
 331 extern JS_PUBLIC_API(void)
 332 JS_PutPropertyDescArray(JSContext *cx, JSPropertyDescArray *pda);
 333
 334 /************************************************************************/
 335
 336 extern JS_PUBLIC_API(JSBool)
 337 JS_SetDebuggerHandler(JSRuntime *rt, JSTrapHandler handler, void *closure);
 338
 339 extern JS_PUBLIC_API(JSBool)
 340 JS_SetSourceHandler(JSRuntime *rt, JSSourceHandler handler, void *closure);
 341
 342 extern JS_PUBLIC_API(JSBool)
 343 JS_SetExecuteHook(JSRuntime *rt, JSInterpreterHook hook, void *closure);
 344
 345 extern JS_PUBLIC_API(JSBool)
 346 JS_SetCallHook(JSRuntime *rt, JSInterpreterHook hook, void *closure);
 347
 348 extern JS_PUBLIC_API(JSBool)
 349 JS_SetObjectHook(JSRuntime *rt, JSObjectHook hook, void *closure);
 350
 351 extern JS_PUBLIC_API(JSBool)
 352 JS_SetThrowHook(JSRuntime *rt, JSTrapHandler hook, void *closure);
 353
 354 extern JS_PUBLIC_API(JSBool)
 355 JS_SetDebugErrorHook(JSRuntime *rt, JSDebugErrorHook hook, void *closure);
 356
 357 /************************************************************************/
 358
 359 extern JS_PUBLIC_API(size_t)
 360 JS_GetObjectTotalSize(JSContext *cx, JSObject *obj);
 361
 362 extern JS_PUBLIC_API(size_t)
 363 JS_GetFunctionTotalSize(JSContext *cx, JSFunction *fun);
 364
 365 extern JS_PUBLIC_API(size_t)
 366 JS_GetScriptTotalSize(JSContext *cx, JSScript *script);
 367
 368 /*
 369  * Get the top-most running script on cx starting from fp, or from the top of
 370  * cx's frame stack if fp is null, and return its script filename flags.  If
 371  * the script has a null filename member, return JSFILENAME_NULL.
 372  */
 373 extern JS_PUBLIC_API(uint32)
 374 JS_GetTopScriptFilenameFlags(JSContext *cx, JSStackFrame *fp);
 375
 376 /*
 377  * Get the script filename flags for the script.  If the script doesn't have a
 378  * filename, return JSFILENAME_NULL.
 379  */
 380 extern JS_PUBLIC_API(uint32)
 381 JS_GetScriptFilenameFlags(JSScript *script);
 382
 383 /*
 384  * Associate flags with a script filename prefix in rt, so that any subsequent
 385  * script compilation will inherit those flags if the script's filename is the
 386  * same as prefix, or if prefix is a substring of the script's filename.
 387  *
 388  * The API defines only one flag bit, JSFILENAME_SYSTEM, leaving the remaining
 389  * 31 bits up to the API client to define.  The union of all 32 bits must not
 390  * be a legal combination, however, in order to preserve JSFILENAME_NULL as a
 391  * unique value.  API clients may depend on JSFILENAME_SYSTEM being a set bit
 392  * in JSFILENAME_NULL -- a script with a null filename member is presumed to
 393  * be a "system" script.
 394  */
 395 extern JS_PUBLIC_API(JSBool)
 396 JS_FlagScriptFilenamePrefix(JSRuntime *rt, const char *prefix, uint32 flags);
 397
 398 #define JSFILENAME_NULL         0xffffffff      /* null script filename */
 399 #define JSFILENAME_SYSTEM       0x00000001      /* "system" script, see below */
 400 #define JSFILENAME_PROTECTED    0x00000002      /* scripts need protection */
 401
 402 /*
 403  * Return true if obj is a "system" object, that is, one created by
 404  * JS_NewSystemObject with the system flag set and not JS_NewObject.
 405  *
 406  * What "system" means is up to the API client, but it can be used to implement
 407  * access control policies based on script filenames and their prefixes, using
 408  * JS_FlagScriptFilenamePrefix and JS_GetTopScriptFilenameFlags.
 409  */
 410 extern JS_PUBLIC_API(JSBool)
 411 JS_IsSystemObject(JSContext *cx, JSObject *obj);
 412
 413 /*
 414  * Call JS_NewObject(cx, clasp, proto, parent) and, if system is true, mark the
 415  * result as a system object, that is an object for which JS_IsSystemObject
 416  * returns true.
 417  */
 418 extern JS_PUBLIC_API(JSObject *)
 419 JS_NewSystemObject(JSContext *cx, JSClass *clasp, JSObject *proto,
 420                    JSObject *parent, JSBool system);
 421
 422 /************************************************************************/
 423
 424 extern JS_PUBLIC_API(JSDebugHooks *)
 425 JS_GetGlobalDebugHooks(JSRuntime *rt);
 426
 427 extern JS_PUBLIC_API(JSDebugHooks *)
 428 JS_SetContextDebugHooks(JSContext *cx, JSDebugHooks *hooks);
 429
 430 #ifdef MOZ_SHARK
 431
 432 extern JS_PUBLIC_API(JSBool)
 433 JS_StartChudRemote();
 434
 435 extern JS_PUBLIC_API(JSBool)
 436 JS_StopChudRemote();
 437
 438 extern JS_PUBLIC_API(JSBool)
 439 JS_ConnectShark();
 440
 441 extern JS_PUBLIC_API(JSBool)
 442 JS_DisconnectShark();
 443
 444 extern JS_FRIEND_API(JSBool)
 445 js_StopShark(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 446              jsval *rval);
 447
 448 extern JS_FRIEND_API(JSBool)
 449 js_StartShark(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 450               jsval *rval);
 451
 452 extern JS_FRIEND_API(JSBool)
 453 js_ConnectShark(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 454                 jsval *rval);
 455
 456 extern JS_FRIEND_API(JSBool)
 457 js_DisconnectShark(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 458                    jsval *rval);
 459
 460 #endif /* MOZ_SHARK */
 461
 462 #ifdef MOZ_CALLGRIND
 463
 464 extern JS_FRIEND_API(JSBool)
 465 js_StopCallgrind(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 466                  jsval *rval);
 467
 468 extern JS_FRIEND_API(JSBool)
 469 js_StartCallgrind(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 470                   jsval *rval);
 471
 472 extern JS_FRIEND_API(JSBool)
 473 js_DumpCallgrind(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 474                  jsval *rval);
 475
 476 #endif /* MOZ_CALLGRIND */
 477
 478 #ifdef MOZ_VTUNE
 479
 480 extern JS_FRIEND_API(JSBool)
 481 js_StartVtune(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 482               jsval *rval);
 483
 484 extern JS_FRIEND_API(JSBool)
 485 js_StopVtune(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 486              jsval *rval);
 487
 488 extern JS_FRIEND_API(JSBool)
 489 js_PauseVtune(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 490               jsval *rval);
 491
 492 extern JS_FRIEND_API(JSBool)
 493 js_ResumeVtune(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
 494                jsval *rval);
 495
 496 #endif /* MOZ_VTUNE */
 497
 498 JS_END_EXTERN_C
 499
 500 #endif /* jsdbgapi_h___ */