Run Format

Source file src/runtime/extern.go

     1	// Copyright 2009 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     5	/*
     6	Package runtime contains operations that interact with Go's runtime system,
     7	such as functions to control goroutines. It also includes the low-level type information
     8	used by the reflect package; see reflect's documentation for the programmable
     9	interface to the run-time type system.
    11	Environment Variables
    13	The following environment variables ($name or %name%, depending on the host
    14	operating system) control the run-time behavior of Go programs. The meanings
    15	and use may change from release to release.
    17	The GOGC variable sets the initial garbage collection target percentage.
    18	A collection is triggered when the ratio of freshly allocated data to live data
    19	remaining after the previous collection reaches this percentage. The default
    20	is GOGC=100. Setting GOGC=off disables the garbage collector entirely.
    21	The runtime/debug package's SetGCPercent function allows changing this
    22	percentage at run time. See http://golang.org/pkg/runtime/debug/#SetGCPercent.
    24	The GODEBUG variable controls debug output from the runtime. GODEBUG value is
    25	a comma-separated list of name=val pairs. Supported names are:
    27		allocfreetrace: setting allocfreetrace=1 causes every allocation to be
    28		profiled and a stack trace printed on each object's allocation and free.
    30		efence: setting efence=1 causes the allocator to run in a mode
    31		where each object is allocated on a unique page and addresses are
    32		never recycled.
    34		gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard
    35		error at each collection, summarizing the amount of memory collected and the
    36		length of the pause. Setting gctrace=2 emits the same summary but also
    37		repeats each collection.
    39		gcdead: setting gcdead=1 causes the garbage collector to clobber all stack slots
    40		that it thinks are dead.
    42		invalidptr: defaults to invalidptr=1, causing the garbage collector and stack
    43		copier to crash the program if an invalid pointer value (for example, 1)
    44		is found in a pointer-typed location. Setting invalidptr=0 disables this check.
    45		This should only be used as a temporary workaround to diagnose buggy code.
    46		The real fix is to not store integers in pointer-typed locations.
    48		scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit
    49		detailed multiline info every X milliseconds, describing state of the scheduler,
    50		processors, threads and goroutines.
    52		schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard
    53		error every X milliseconds, summarizing the scheduler state.
    55		scavenge: scavenge=1 enables debugging mode of heap scavenger.
    57	The GOMAXPROCS variable limits the number of operating system threads that
    58	can execute user-level Go code simultaneously. There is no limit to the number of threads
    59	that can be blocked in system calls on behalf of Go code; those do not count against
    60	the GOMAXPROCS limit. This package's GOMAXPROCS function queries and changes
    61	the limit.
    63	The GOTRACEBACK variable controls the amount of output generated when a Go
    64	program fails due to an unrecovered panic or an unexpected runtime condition.
    65	By default, a failure prints a stack trace for every extant goroutine, eliding functions
    66	internal to the run-time system, and then exits with exit code 2.
    67	If GOTRACEBACK=0, the per-goroutine stack traces are omitted entirely.
    68	If GOTRACEBACK=1, the default behavior is used.
    69	If GOTRACEBACK=2, the per-goroutine stack traces include run-time functions.
    70	If GOTRACEBACK=crash, the per-goroutine stack traces include run-time functions,
    71	and if possible the program crashes in an operating-specific manner instead of
    72	exiting. For example, on Unix systems, the program raises SIGABRT to trigger a
    73	core dump.
    75	The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete
    76	the set of Go environment variables. They influence the building of Go programs
    77	(see http://golang.org/cmd/go and http://golang.org/pkg/go/build).
    78	GOARCH, GOOS, and GOROOT are recorded at compile time and made available by
    79	constants or functions in this package, but they do not influence the execution
    80	of the run-time system.
    81	*/
    82	package runtime
    84	// Caller reports file and line number information about function invocations on
    85	// the calling goroutine's stack.  The argument skip is the number of stack frames
    86	// to ascend, with 0 identifying the caller of Caller.  (For historical reasons the
    87	// meaning of skip differs between Caller and Callers.) The return values report the
    88	// program counter, file name, and line number within the file of the corresponding
    89	// call.  The boolean ok is false if it was not possible to recover the information.
    90	func Caller(skip int) (pc uintptr, file string, line int, ok bool) {
    91		// Ask for two PCs: the one we were asked for
    92		// and what it called, so that we can see if it
    93		// "called" sigpanic.
    94		var rpc [2]uintptr
    95		if callers(1+skip-1, &rpc[0], 2) < 2 {
    96			return
    97		}
    98		f := findfunc(rpc[1])
    99		if f == nil {
   100			// TODO(rsc): Probably a bug?
   101			// The C version said "have retpc at least"
   102			// but actually returned pc=0.
   103			ok = true
   104			return
   105		}
   106		pc = rpc[1]
   107		xpc := pc
   108		g := findfunc(rpc[0])
   109		// All architectures turn faults into apparent calls to sigpanic.
   110		// If we see a call to sigpanic, we do not back up the PC to find
   111		// the line number of the call instruction, because there is no call.
   112		if xpc > f.entry && (g == nil || g.entry != funcPC(sigpanic)) {
   113			xpc--
   114		}
   115		line = int(funcline(f, xpc, &file))
   116		ok = true
   117		return
   118	}
   120	// Callers fills the slice pc with the return program counters of function invocations
   121	// on the calling goroutine's stack.  The argument skip is the number of stack frames
   122	// to skip before recording in pc, with 0 identifying the frame for Callers itself and
   123	// 1 identifying the caller of Callers.
   124	// It returns the number of entries written to pc.
   125	//
   126	// Note that since each slice entry pc[i] is a return program counter,
   127	// looking up the file and line for pc[i] (for example, using (*Func).FileLine)
   128	// will return the file and line number of the instruction immediately
   129	// following the call.
   130	// To look up the file and line number of the call itself, use pc[i]-1.
   131	// As an exception to this rule, if pc[i-1] corresponds to the function
   132	// runtime.sigpanic, then pc[i] is the program counter of a faulting
   133	// instruction and should be used without any subtraction.
   134	func Callers(skip int, pc []uintptr) int {
   135		// runtime.callers uses pc.array==nil as a signal
   136		// to print a stack trace.  Pick off 0-length pc here
   137		// so that we don't let a nil pc slice get to it.
   138		if len(pc) == 0 {
   139			return 0
   140		}
   141		return callers(skip, &pc[0], len(pc))
   142	}
   144	// GOROOT returns the root of the Go tree.
   145	// It uses the GOROOT environment variable, if set,
   146	// or else the root used during the Go build.
   147	func GOROOT() string {
   148		s := gogetenv("GOROOT")
   149		if s != "" {
   150			return s
   151		}
   152		return defaultGoroot
   153	}
   155	// Version returns the Go tree's version string.
   156	// It is either the commit hash and date at the time of the build or,
   157	// when possible, a release tag like "go1.3".
   158	func Version() string {
   159		return theVersion
   160	}
   162	// GOOS is the running program's operating system target:
   163	// one of darwin, freebsd, linux, and so on.
   164	const GOOS string = theGoos
   166	// GOARCH is the running program's architecture target:
   167	// 386, amd64, or arm.
   168	const GOARCH string = theGoarch

View as plain text