Move man pages from man5 to man3 (3stap).

1 files changed, 0 insertions, 668 deletions

diff --git a/stapfuncs.5.in b/stapfuncs.5.in
deleted file mode 100644
index 0322369e..00000000
--- a/stapfuncs.5.in
+++ /dev/null
@@ -1,668 +0,0 @@
-.\" -*- nroff -*-
-.TH STAPFUNCS 5 @DATE@ "Red Hat"
-.SH NAME
-stapfuncs \- systemtap functions
-
-.SH DESCRIPTION
-The following sections enumerate the public functions provided by
-standard tapsets installed under @prefix@/share/systemtap/tapset.  Each
-function is described with a signature, and its behavior/restrictions.
-The signature line includes the name of the function, the type of
-its return value (if any), and the names and types of all parameters.
-The syntax is the same as printed with the 
-.IR stap " option " \-p2 .
-Examples:
-
-.TP
-example1:long (v:string, k:long)
-In function "example1", do something with the given string and integer.
-Return some integer.
-
-.TP
-example2:unknown ()
-In function "example2", do something.  There is no explicit return value
-and take no parameters.
-
-.SS PRINTING
-
-.TP
-log:unknown (msg:string)
-Writes the given string to the common trace buffer.  Append an implicit
-end-of-line. Deprecated.  Please use the faster print functions.
-
-.TP
-warn:unknown (msg:string)
-Write the given string to the warning stream.  Append an implicit end-of-line.
-.I staprun
-prepends the string "WARNING:". 
-
-.TP
-error:unknown (msg:string)
-An error has occurred.  Write the given string to the error stream.
-Append an implicit end-of-line.
-.I staprun
-prepends the string "ERROR:".
-Block any further execution of statements in this probe.  If the number
-of errors so far exceeds the MAXERRORS parameter, also trigger an 
-.IR exit() .
-
-.TP
-exit:unknown ()
-Enqueue a request to shut down the systemtap session.  This does
-.B not
-unwind the current probe handler, nor block new probe handlers.
-.I staprun
-will shortly respond to the request and initiate an orderly shutdown.
-
-.SS CONVERSIONS
-.PP
-These functions access kernel or user-space data.  They try to validate the
-supplied addresses, and can thus result in errors if the pointers are invalid,
-or if a user-space access would cause a fault.
-.TP
-kernel_string:string (addr:long)
-Copy a 0-terminated string from kernel space at given address.
-.TP
-kernel_string_n:string (addr:long, n:long)
-Similar with kernel_string, except that not more than n bytes are copied.
-Thus, if there are null bytes among the first n bytes, it is same as
-kernel_string(addr). If not, n bytes will be copied and a null byte will
-be padded to the end.
-.TP
-kernel_long:long (addr:long)
-Copy a long from kernel space at given address.
-.TP
-kernel_int:long (addr:long)
-Copy an int from kernel space at given address.
-.TP
-kernel_short:long (addr:long)
-Copy a short from kernel space at given address.
-.TP
-kernel_char:long (addr:long)
-Copy a char from kernel space at given address.
-.TP
-user_string:string (addr:long)
-Copy a string from user space at given address.  If the access would
-fault, return "<unknown>" and signal no errors.
-.TP
-user_string2:string (addr:long, err_msg:string)
-Copy a string from user space at given address.  If the access would
-fault, return instead the err_msg value.
-.TP
-user_string_warn:string (addr:long)
-Copy a string from user space at given address.  If the access would
-fault, signal a warning and return "<unknown>".
-.TP
-user_string_quoted:string (addr:long)
-Copy a string from user space at given address. Any ASCII characters
-that are not printable are replaced by the corresponding escape
-sequence in the returned string.
-.TP
-user_string_n:string (addr:long, n:long)
-Copy a string of n bytes from user space at given address. If the access
-would fault, return "<unknown>".
-.TP
-user_string_n2:string (addr:long, n:long, err_msg:string)
-Copy a string of n bytes from user space at given address. If the access
-would fault, return the err_msg value.
-.TP
-user_string_n_warn:string (addr:long, n:long)
-Copy a string of n bytes from user space at given address. If the access
-would fault, signal a warning and return "<unknown>".
-.TP
-user_string_n_quoted:string (addr:long, n:long)
-Copy a string of n bytes from user space at given address. Any ASCII
-characters that are not printable are replaced by the corresponding escape
-sequence in the returned string. If the access would fault, return "<unknown>".
-.TP
-user_short:long (addr:long)
-Copy a short from user space at given address. If the access would fault,
-return 0.
-.TP
-user_short_warn:long (addr:long)
-Copy a short from user space at given address. If the access would fault,
-signal a warning and return 0.
-.TP
-user_int:long (addr:long)
-Copy an int from user space at given address. If the access would fault,
-return 0.
-.TP
-user_int_warn:long (addr:long)
-Copy an int from user space at given address. If the access would fault,
-signal a warning and return 0.
-.TP
-user_long:long (addr:long)
-Copy a long from user space at given address. If the access would fault,
-return 0.
-.TP
-user_long_warn:long (addr:long)
-Copy a long from user space at given address. If the access would fault,
-signal a warning and return 0.
-.TP
-user_char:long (addr:long)
-Copy a char from user space at given address. If the access would fault,
-return 0.
-.TP
-user_char_warn:long (addr:long)
-Copy a char from user space at given address. If the access would fault,
-signal a warning and return 0.
-.SS STRING
-.TP
-strlen:long (str:string)
-Return the number of characters in str.
-.TP
-substr:string (str:string,start:long, stop:long)
-Return the substring of str starting from character start and ending at character stop.
-.TP
-isinstr:long (s1:string, s2:string)
-Return 1 if string s1 contains string s2, returns 0 otherwise.
-.TP
-strtol:long (str:string, base:long)
-Convert the string representation of a number to a long using the numbering system
-specified by base.  For example, strtol("1000", 16) returns 4096.  Returns 0 if the
-string cannot be converted.
-.TP
-tokenize:string (str:string, delim:string)
-Return the next token in the given str string, where the tokens are delimited
-by one of the characters in the delim string.  If the str string is not blank,
-it returns the first token.  If the str string is blank, it returns the next
-token in the string passed in the previous call to tokenize. If no delimiter
-is found, the entire remaining str string is returned.  Returns blank when 
-no more tokens are left.
-
-.SS TIMESTAMP
-.TP
-get_cycles:long ()
-Return the processor cycle counter value, or 0 if unavailable.
-.TP
-gettimeofday_ns:long ()
-Return the number of nanoseconds since the UNIX epoch.
-.TP
-gettimeofday_us:long ()
-Return the number of microseconds since the UNIX epoch.
-.TP
-gettimeofday_ms:long ()
-Return the number of milliseconds since the UNIX epoch.
-.TP
-gettimeofday_s:long ()
-Return the number of seconds since the UNIX epoch.
-
-.SS CONTEXT INFO
-.TP
-cpu:long ()
-Return the current cpu number.
-.TP
-execname:string ()
-Return the name of the current process.
-.TP
-pexecname:string()
-Return the name of the parent process.
-.TP
-tid:long ()
-Return the id of the current thread.
-.TP
-pid:long ()
-Return the id of the current process.
-.TP
-ppid:long ()
-Return the id of the parent process.
-.TP
-uid:long ()
-Return the uid of the current process.
-.TP
-euid:long ()
-Return the effective uid of the current process.
-.TP
-gid:long ()
-Return the gid of the current process.
-.TP
-egid:long ()
-Return the effective gid of the current process.
-.TP
-print_regs:unknown ()
-Print a register dump.
-.TP
-backtrace:string ()
-Return a string of hex addresses that are a backtrace of the stack.
-It may be truncated due to maximum string length.
-.TP
-print_stack:unknown (bt:string)
-Perform a symbolic lookup of the addresses in the given string,
-which is assumed to be the result of a prior call to
-.IR backtrace() .
-Print one line per address, including the address, the name of the
-function containing the address, and an estimate of its position
-within that function.  Return nothing.
-.TP
-print_backtrace:unknown ()
-Equivalent to
-.IR print_stack(backtrace()) ,
-except that deeper stack nesting may be supported.  Return nothing.
-.TP
-pp:string ()
-Return the probe point associated with the currently running probe handler,
-including alias and wildcard expansion effects.
-.TP
-probefunc:string ()
-Return the probe point's function name, if known.
-.TP
-probemod:string ()
-Return the probe point's module name, if known.
-.TP
-target:long ()
-Return the pid of the target process.
-.TP
-user_mode:long ()
-Return 1 if the probe point occurred in user-mode.
-.TP
-is_return:long ()
-Return 1 if the probe point is a return probe.  Deprecated.
-
-.SS TARGET_SET
-.TP
-target_set_pid:long (tid:long)
-Return whether the given process-id is within the "target set", that is whether
-it is a descendent of the top-level target() process.
-.TP
-target_set_report:unknown ()
-Print a report about the target set, and their ancestry. 
-
-.SS ERRNO
-.TP
-errno_str:string (e:long)
-Return the symbolic string associated with the given error code, like
-"ENOENT" for the number 2, or "E#3333" for an out-of-range value like 3333.
-
-.SS TASK
-.PP
-These functions return data about a task.  They all require
-a task handle as input, such as the value return by task_current() or the variables
-prev_task and next_task in the scheduler.ctxswitch probe alias.
-
-.TP
-task_current:long()
-Return the task_struct of the current process.
-
-.TP
-task_parent:long(task:long)
-Return the parent task_struct of the given task.
-.TP
-task_state:long(task:long)
-Return the state of the given task, which can be one of the following:
-
-   TASK_RUNNING           0
-   TASK_INTERRUPTIBLE     1
-   TASK_UNINTERRUPTIBLE   2
-   TASK_STOPPED           4
-   TASK_TRACED            8
-   EXIT_ZOMBIE           16
-   EXIT_DEAD             32
-
-.TP
-task_execname:string(task:long)
-Return the name of the given task.
-
-.TP
-task_pid:long(task:long)
-Return the process id of the given task.
-
-.TP
-task_tid:long(task:long)
-Return the thread id of the given task.
-
-.TP
-task_gid:long(task:long)
-Return the group id of the given task.
-
-.TP
-task_egid:long(task:long)
-Return the effective group id of the given task.
-
-.TP
-task_uid:long(task:long)
-Return the user id of the given task.
-
-.TP
-task_euid:long(task:long)
-Return the effective user id of the given task.
-
-.TP
-task_prio:long(task:long)
-Return the priority of the given task.
-
-.TP
-task_nice:long(task:long)
-Return the nice value of the given task.
-
-.TP
-task_cpu:long(task:long)
-Return the scheduled cpu for the given task.
-
-.TP
-task_open_file_handles:long(task:long)
-Return the number of open file handles for the given task.
-
-.TP
-task_max_file_handles:long(task:long)
-Return the maximum number of file handles for the given task.
-
-.SS CPU REGISTERS
-.TP
-registers_valid:long ()
-Return 1 if register() and u_register() can be used
-in the current context, or 0 otherwise.
-For example, registers_valid() returns 0 when called from a begin or end probe.
-.TP
-register:long (name:string)
-Return the value of the named CPU register,
-as it was saved when the current probe point was hit.
-If the register is 32 bits, it is sign-extended to 64 bits.
-
-For the i386 architecture, the following names are recognized.
-(name1/name2 indicates that name1 and name2 are alternative names
-for the same register.)
-eax/ax, ebp/bp, ebx/bx, ecx/cx, edi/di, edx/dx, eflags/flags,
-eip/ip, esi/si, esp/sp, orig_eax/orig_ax,
-xcs/cs, xds/ds, xes/es, xfs/fs, xss/ss.
-
-For the x86_64 architecture, the following names are recognized:
-64-bit registers:
-r8, r9, r10, r11, r12, r13, r14, r15,
-rax/ax, rbp/bp, rbx/bx, rcx/cx, rdi/di, rdx/dx,
-rip/ip, rsi/si, rsp/sp;
-32-bit registers:
-eax, ebp, ebx, ecx, edx, edi, edx, eip, esi, esp, flags/eflags, orig_eax;
-segment registers: xcs/cs, xss/ss.
-
-For powerpc, the following names are recognized:
-r0, r1, ... r31, nip, msr, orig_gpr3, ctr, link, xer, ccr, softe, trap,
-dar, dsisr, result.
-
-For s390x, the following names are recognized:
-r0, r1, ... r15, args, psw.mask, psw.addr, orig_gpr2, ilc, trap.
-
-.TP
-u_register:long (name:string)
-Same as register(name), except that
-if the register is 32 bits, it is zero-extended to 64 bits.
-
-.SS NUMBERED FUNCTION ARGUMENTS
-The functions in this section provide the values of a probed function's
-arguments.
-They can be called when you have hit
-a probe point at the entry to a function.
-Arguments are referred to by number, starting at 1.
-Ordinarily, you can access arguments by name as well,
-but you may find these functions useful if the code you are probing
-was built without debugging information.
-
-On 32-bit architectures
-\(em and when probing 32-bit applications on 64-bit architectures \(em
-a 64-bit argument occupies two "arg slots."
-For example, if you are probing the following function
-
-   void f(int a, long long b, char *c)
-
-you would refer to a, b, and c as int_arg(1), longlong_arg(2), and
-pointer_arg(3), respectively, on a 64-bit architecture;
-but on a 32-bit architecture, you would refer to c as pointer_arg(4)
-(since b occupies slots 2 and 3).
-
-If the function you are probing doesn't follow the default rules
-for argument passing, you need to call one of the following functions
-(which see) in your handler before calling any *_arg function:
-asmlinkage(), fastcall(), or regparm().
-(This isn't necessary when referring to arguments only by name.)
-.TP
-int_arg:long (n:long)
-Return the value of argument n as a signed int
-(i.e., a 32-bit integer sign-extended to 64 bits).
-.TP
-uint_arg:long (n:long)
-Return the value of argument n as an unsigned int
-(i.e., a 32-bit integer zero-extended to 64 bits).
-.TP
-long_arg:long (n:long)
-Return the value of argument n as a signed long.
-On architectures where a long is 32 bits, the value is sign-extended to 64 bits.
-.TP
-ulong_arg:long (n:long)
-Return the value of argument n as an unsigned long.
-On architectures where a long is 32 bits, the value is zero-extended to 64 bits.
-.TP
-longlong_arg:long (n:long)
-Return the value of argument n as a 64-bit value.
-.TP
-ulonglong_arg:long (n:long)
-Same as longlong_arg(n).
-.TP
-pointer_arg:long (n:long)
-Same as ulong_arg(n).
-Use with any type of pointer.
-.TP
-s32_arg:long (n:long)
-Same as int_arg(n).
-.TP
-u32_arg:long (n:long)
-Same as uint_arg(n).
-.TP
-s64_arg:long (n:long)
-Same as longlong_arg(n).
-.TP
-u64_arg:long (n:long)
-Same as [u]longlong_arg(n).
-.TP
-asmlinkage:unknown ()
-The probed kernel function is declared asmlinkage in the source.
-.TP
-fastcall:unknown ()
-The probed kernel function is declared fastcall in the source.
-.TP
-regparm:unknown (n:long)
-The probed function was built with the gcc \-mregparm=n option.
-(The i386 kernel is built with \-mregparm=3, so systemtap considers
-regparm(3) the default for kernel functions on that architecture.)
-
-For some architectures, the *_arg functions may reject unusually high
-values of n.
-
-.SS QUEUE_STATS
-.PP
-The queue_stats tapset provides functions that, given notifications of
-elementary queuing events (wait, run, done), tracks averages such as
-queue length, service and wait times, utilization.  The following
-three functions should be called from appropriate probes, in sequence.
-.TP
-qs_wait:unknown (qname:string)
-Record that a new request was enqueued for the given queue name.
-.TP
-qs_run:unknown (qname:string)
-Record that a previously enqueued request was removed from the given
-wait queue and is now being serviced.
-.TP
-qs_done:unknown (qname:string)
-Record that a request originally from the given queue has completed
-being serviced.
-.\" XXX: qs_time
-.PP
-Functions with the prefix 
-.BR qsq_
-are for querying the statistics averaged since the first queue operation
-(or when
-.BR qsq_start
-was called). Since statistics are often fractional, a scale parameter
-is multiplies the result to a more useful scale.  For some fractions,
-a scale of 100 will usefully return percentage numbers.
-.TP
-qsq_start:unknown (qname:string)
-Reset the statistics counters for the given queue, and start tracking
-anew from this moment.
-.TP
-qsq_print:unknown (qname:string)
-Print a line containing a selection of the given queue's statistics.
-.TP
-qsq_utilization:long (qname:string, scale:long)
-Return the fraction of elapsed time when the resource was utilized.
-.TP
-qsq_blocked:long (qname:string, scale:long)
-Return the fraction of elapsed time when the wait queue was used.
-.TP
-qsq_wait_queue_length:long (qname:string, scale:long)
-Return the average length of the wait queue.
-.TP
-qsq_service_time:long (qname:string, scale:long)
-Return the average time required to service a request.
-.TP
-qsq_wait_time:long (qname:string, scale:long)
-Return the average time a request took from being enqueued to completed.
-.TP
-qsq_throughput:long (qname:string, scale:long)
-Return the average rate of requests per scale units of time.
-
-.SS INDENT
-.PP
-The indent tapset provides functions to generate indented lines for
-nested kinds of trace messages.  Each line contains a relative
-timestamp, and the process name / pid.
-.TP
-thread_indent:string (delta:long)
-Return a string with an appropriate indentation for this thread.
-Call it with a small positive or matching negative delta.
-If this is the outermost, initial level of indentation, reset the
-relative timestamp base to zero.
-.TP
-thread_timestamp:long ()
-Return an absolute timestamp value for use by the indentation function.
-The default function uses 
-.IR gettimeofday_us
-
-.SS SYSTEM
-.TP
-system (cmd:string)
-Runs a command on the system. The command will run in the background
-when the current probe completes.
-
-.SS NUMA
-.TP
-addr_to_node:long (addr:long)
-Return which node the given address belongs to in a NUMA system.
-
-.SS CTIME
-.TP
-ctime:string (seconds:long)
-Return a simple textual rendering (e.g., "Wed\ Jun\ 30\ 21:49:008\ 1993")
-of the given number of seconds since the epoch, as perhaps returned by
-.IR gettimeofday_s() .
-
-.SS PERFMON
-.TP
-read_counter:long (handle:long)
-Returns the value for the processor's performance counter for the associated
-handle. The body of the a perfmon probe should set record
-the handle being used for that event.
-
-.SS SOCKETS
-These functions convert arguments in the socket tapset back and
-forth between their numeric and string representations.
-See 
-.IR stapprobes.socket (5)
-for details.
-
-.TP
-sock_prot_num2str:string (proto:long)
-Returns the string representation of the given protocol value.
-.TP
-sock_prot_str2num:long (proto:string)
-Returns the numeric value associated with the given protocol string.
-.TP
-sock_fam_num2str:string (family:long)
-Returns the string representation of the given protocol family value.
-.TP
-sock_fam_str2num:long (family:string)
-Returns the numeric value associated with the given protocol family string.
-.TP
-sock_state_num2str:string (state:long)
-Returns the string representation of the given socket state value.
-.TP
-sock_state_str2num:long (state:string)
-Returns the numeric value associated with the given socket state string.
-.TP
-sock_type_num2str:string (type:long)
-Returns the string representation of the given socket type value.
-.TP
-sock_type_str2num:long (type:string)
-Returns the numeric value associated with the given socket type string.
-.TP
-sock_flags_num2str:string (flags:long)
-Returns the string representation of the given socket flags value.
-.TP
-msg_flags_num2str:string (flags:long)
-Returns the string representation of the given message flags bit map.
-
-.SS INET
-These functions convert between network (big-endian) and host byte order, like their
-namesake C functions.
-.TP
-ntohll:long (x:long)
-Convert from network to host byte order, 64-bit.
-.TP
-ntohl:long (x:long)
-Convert from network to host byte order, 32-bit.
-.TP
-ntohs:long (x:long)
-Convert from network to host byte order, 16-bit.
-.TP
-htonll:long (x:long)
-Convert from host to network byte order, 64-bit.
-.TP
-htonl:long (x:long)
-Convert from host to network byte order, 32-bit.
-.TP
-htons:long (x:long)
-Convert from host to network byte order, 16-bit.
-
-.SS SIGNAL
-.TP
-get_sa_flags:long (act:long)
-Returns the numeric value of sa_flags.
-.TP
-get_sa_handler:long (act:long)
-Returns the numeric value of sa_handler.
-.TP
-sigset_mask_str:string (mask:long)
-Returns the string representation of the sigset sa_mask.
-.TP
-is_sig_blocked:long (task:long, sig:long)
-Returns 1 if the signal is currently blocked, or 0 if it is not.
-.TP
-sa_flags_str:string (sa_flags:long)
-Returns the string representation of sa_flags.
-.TP
-sa_handler_str(handler)
-Returns the string representation of sa_handler. If it is not SIG_DFL, SIG_IGN
-or SIG_ERR, it will return the address of the handler.
-.TP
-signal_str(num)
-Returns the string representation of the given signal number.
-
-.SS DEVICE
-.TP
-MAJOR:long(dev:long)
-Extracts the major device number from a kernel device number (kdev_t).
-.TP
-MINOR:long(dev:long)
-Extracts the minor device number from a kernel device number (kdev_t).
-.TP
-MKDEV:long(major:long, minor:long)
-Creates a value that can be compared to a kernel device number (kdev_t).
-.TP
-usrdev2kerndev:long(dev:long)
-Converts a user-space device number into the format used in the kernel.
-
-.SH FILES
-.nh
-.IR @prefix@/share/systemtap/tapset
-.hy
-
-.SH SEE ALSO
-.IR stap (1)