[src/trunk]: src Document CTL_PROC, the core filename format it core(5), and ...

[bouyer <bouyer%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/8572c26411fd
branches:  trunk
changeset: 476805:8572c26411fd
user:      bouyer <bouyer%NetBSD.org@localhost>
date:      Tue Sep 28 14:52:32 1999 +0000

description:
Document CTL_PROC, the core filename format it core(5), and xref sysctl(8),
sysctl(3), core(5) in various place.
Document 'options DEFCORENAME' inj options(4) and $defcorename in rc.conf(5).

diffstat:

 lib/libc/gen/sysctl.3    |  100 ++++++++++++++++++++++++++++++++++++++++------
 lib/libc/sys/getrlimit.2 |    6 +-
 share/man/man4/options.4 |   18 +++----
 share/man/man5/core.5    |   70 +++++++++++++++++++-------------
 share/man/man5/rc.conf.5 |   13 +++++-
 5 files changed, 153 insertions(+), 54 deletions(-)

diffs (truncated from 336 to 300 lines):

diff -r 6c6b5b7e8e82 -r 8572c26411fd lib/libc/gen/sysctl.3
--- a/lib/libc/gen/sysctl.3     Tue Sep 28 14:48:48 1999 +0000
+++ b/lib/libc/gen/sysctl.3     Tue Sep 28 14:52:32 1999 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sysctl.3,v 1.37 1999/09/27 16:24:40 kleink Exp $
+.\"    $NetBSD: sysctl.3,v 1.38 1999/09/28 14:52:32 bouyer Exp $
 .\"
 .\" Copyright (c) 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -127,6 +127,7 @@
 .It CTL\_KERN  sys/sysctl.h    High kernel limits
 .It CTL\_MACHDEP       sys/sysctl.h    Machine dependent
 .It CTL\_NET   sys/socket.h    Networking
+.It CTL\_PROC  sys/sysctl.h    Per-process
 .It CTL\_USER  sys/sysctl.h    User-level
 .It CTL\_VM    vm/vm_param.h   Virtual memory
 .El
@@ -255,6 +256,7 @@
 .It KERN\_BOOTTIME     struct timeval  no
 .It KERN\_CHOWN\_RESTRICTED    integer no
 .It KERN\_CLOCKRATE    struct clockinfo        no
+.It KERN\_DEFCORENAME  string  yes
 .It KERN\_DOMAINNAME   string  yes
 .It KERN\_FILE struct file     no
 .It KERN\_FSYNC        integer no
@@ -289,7 +291,6 @@
 .It KERN\_RAWPARTITION integer no
 .It KERN\_SAVED\_IDS   integer no
 .It KERN\_SECURELVL    integer raise only
-.It KERN\_SHORTCORENAME        integer yes
 .It KERN\_SYNCHRONIZED\_IO     integer no
 .It KERN\_SYSVMSG      integer no
 .It KERN\_SYSVSEM      integer no
@@ -327,6 +328,17 @@
 This structure contains the clock, statistics clock and profiling clock
 frequencies, the number of micro-seconds per hz tick, and the clock
 skew rate.
+.It Li KERN_DEFCORENAME
+Default template for the name of core dump files (see also PROC_PID_CORENAME
+in the per-process variables CTL_PROC, and
+.Xr core 5
+for format of this template).  The default value is
+.Nm %n.core
+and can be changed with the kernel configuration option
+.Cd options DEFCORENAME
+(see 
+.Xr options 4
+).
 .It Li KERN_DOMAINNAME
 Get or set the YP domain name.
 .It Li KERN_FILE
@@ -470,17 +482,6 @@
 The system security level.
 This level may be raised by processes with appropriate privilege.
 It may only be lowered by process 1.
-.It Li KERN_SHORTCORENAME
-Whether core dumps are named 
-.Nm programname.core
-(default, value 0) or 
-.Nm core
-(value 1).
-The default value can be changed to 1 with the kernel configuration option
-.Cd options SHORTCORENAME
-(see 
-.Xr options 4 ,
-.Xr core 5 ).
 .It Li KERN_SYNCHRONIZED_IO
 Returns 1 if the POSIX 1003.1b Synchronized I/O Option is available
 on this system,
@@ -721,6 +722,79 @@
 Returns the default UDP receive buffer size.
 .El
 .El
+.Sh CTL_PROC
+The string and integer information available for the CTL_PROC
+is detailed below.
+The changeable column shows whether a process with appropriate
+privilege may change the value.
+These values are per-process, and as such may change from one process
+to another. When a process is created, the default values are inherited from
+its parent. When a set-user-ID or set-group-ID binary is executed, the
+value of PROC_PID_CORENAME is reset to the system default value.
+The second level name is either the magic value PROC_CURPROC, which
+points to the current process, or the PID of the target process.
+.Bl -column "USER_COLL_WEIGHTS_MAXXXX" "integerXXX" "yes" -offset indent
+.It Sy Pa Third level name     Type    Changeable
+.It PROC\_PID\_CORENAME        string  yes
+.It PROC\_PID\_LIMIT   node    not applicable
+.El
+.Bl -tag -width "123456"
+.Pp
+.It Li PROC_PID_CORENAME
+The template used for the core dump file name (see
+.Xr core 5
+for details). The base name must either be 
+.Nm core
+or end with the suffix ``.core'' (the super-user may set arbitrary names). By
+default it points to KERN_DEFCORENAME.
+.It Li PROC_PID_LIMIT
+Return resources limits, as defined for the
+.Xr getrlimit 2
+and 
+.Xr setrlimit 2
+system calls.
+The fourth level name is one of:
+.Bl -tag -width PROC_PID_LIMIT_MEMLOCKAA
+.It Li PROC_PID_LIMIT_CPU
+The maximum amount of cpu time (in seconds) to be used by each process.
+.It Li PROC_PID_LIMIT_FSIZE
+The largest size (in bytes) file that may be created.
+.It Li PROC_PID_LIMIT_DATA
+The maximum size (in bytes) of the data segment for a process;
+this defines how far a program may extend its break with the
+.Xr sbrk 2
+system call.
+.It Li PROC_PID_LIMIT_STACK
+The maximum size (in bytes) of the stack segment for a process;
+this defines how far a program's stack segment may be extended.
+Stack extension is performed automatically by the system.
+.It Li PROC_PID_LIMIT_CORE
+The largest size (in bytes)
+.Pa core
+file that may be created.
+.It Li PROC_PID_LIMIT_RSS
+The maximum size (in bytes) to which a process's resident set size may
+grow.
+This imposes a limit on the amount of physical memory to be given to
+a process; if memory is tight, the system will prefer to take memory
+from processes that are exceeding their declared resident set size.
+.It Li PROC_PID_LIMIT_MEMLOCK
+The maximum size (in bytes) which a process may lock into memory
+using the
+.Xr mlock 2
+function.
+.It Li PROC_PID_LIMIT_NPROC
+The maximum number of simultaneous processes for this user id.
+.It Li PROC_PID_LIMIT_NOFILE
+The maximum number of open files for this process.
+.El
+.Pp
+The fifth level name is one of PROC_PID_LIMIT_TYPE_SOFT or
+PROC_PID_LIMIT_TYPE_HARD, to select respectively the soft or hard limit.
+Both are of type integer.
+.El
+.Pp
+
 .Sh CTL_USER
 The string and integer information available for the CTL_USER level
 is detailed below.
diff -r 6c6b5b7e8e82 -r 8572c26411fd lib/libc/sys/getrlimit.2
--- a/lib/libc/sys/getrlimit.2  Tue Sep 28 14:48:48 1999 +0000
+++ b/lib/libc/sys/getrlimit.2  Tue Sep 28 14:52:32 1999 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getrlimit.2,v 1.13 1999/03/22 19:45:04 garbled Exp $
+.\"    $NetBSD: getrlimit.2,v 1.14 1999/09/28 14:52:33 bouyer Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -54,7 +54,9 @@
 .Fn getrlimit
 call, and set with the
 .Fn setrlimit
-call.  
+call.  Resources of an arbitrary process can be obtained/changed using
+.Xr sysctl 3 .
+..
 .Pp
 The
 .Fa resource
diff -r 6c6b5b7e8e82 -r 8572c26411fd share/man/man4/options.4
--- a/share/man/man4/options.4  Tue Sep 28 14:48:48 1999 +0000
+++ b/share/man/man4/options.4  Tue Sep 28 14:52:32 1999 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: options.4,v 1.87 1999/09/24 17:18:14 itojun Exp $
+.\"    $NetBSD: options.4,v 1.88 1999/09/28 14:52:33 bouyer Exp $
 .\"
 .\" Copyright (c) 1996
 .\"    Perry E. Metzger.  All rights reserved.
@@ -837,18 +837,16 @@
 .Em CHILD_MAX
 is not permitted, as this would result in a violation of the semantics of
 .St -p1003.1-90 .
-.It Cd options SHORTCORENAME
-If set, process core dumps are named 
-.Nm core .
-If not specified, they are named
-.Nm programname.core 
-(the default in 4.4BSD). Note that this changes the value of the 
-.Em kern.shortcorename 
-sysctl variable which may be changed at run time. See
+.It Cd options DEFCORENAME=string
+Sets the default value of the
+.Em kern.defcorename
+sysctl variable, otherwise it is set to
+.Nm %n.core .
+See
 .Xr sysctl 8
 and
 .Xr sysctl 3
-for details. 
+for details.
 .El
 .Ss Networking Options
 .Bl -ohang
diff -r 6c6b5b7e8e82 -r 8572c26411fd share/man/man5/core.5
--- a/share/man/man5/core.5     Tue Sep 28 14:48:48 1999 +0000
+++ b/share/man/man5/core.5     Tue Sep 28 14:52:32 1999 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: core.5,v 1.8 1999/03/17 20:19:44 garbled Exp $
+.\"    $NetBSD: core.5,v 1.9 1999/09/28 14:52:33 bouyer Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -47,33 +47,49 @@
 to disk for later examination by one of the available debuggers.
 (See
 .Xr sigaction 2 . )
-This memory image is written to a file 
-in the working directory;
-provided the terminated process had write permission in the directory,
-and provided the abnormality did not cause
-a system crash.
+This memory image is written to a file named from a per-process template;
+provided the terminated process had write permission, and provided the
+abnormality did not cause a system crash.
 (In this event, the decision to save the core file is arbitrary, see
 .Xr savecore 8 . )
-The file is normally named 
-.Nm programname.core ,
-but is called
-.Nm core
-if the 
-kernel configuration option 
-.Cd options SHORTCORENAME
-is defined or the sysctl variable
-.Em kern.shortcorename
-is set to 1.
+The file is named from a per-process template, mapped to the sysctl
+variable
+.Em proc.<pid>.corename
+(where <pid> has to be remplaced by the pid in decimal format of the
+process).
+This template is either an absolute or relative path name, in which format
+characters can be used, preceeded by the percent character (``%''). 
+The following characters are recognised as format and subsitued:
+.Bl -column "cAA" "The process's creation date (in seconds)xxx" -offset indent
+.It Li n        The process's name
+.It Li p        The PID of the process (in decimal) 
+.It Li t        The process's creation date (a la
+.Xr time 3 ,
+in decimal)
+.It Li u        The login name, as returned by
+.Xr getlogin 2
+.El
 .Pp
-The maximum size of a
-.Nm programname.core
-file is limited by
+By default, the per-process template string points to the default core name
+template, which is mapped to the sysctl variable
+.Em kern.defcorename .
+Changing this value on a live system will change the core name template for
+all processes which didn't have a per-process template set.
+The default value of the default core name template is
+.Nm %n.core
+and can be changed at compile-time with the kernel configuration option
+.Cd options DEFCORENAME
+(see
+.Xr options 4 )
+.Pp
+The per-process template string is inherited on process creation, but is reset
+to point to the default core name template on execution of a set-id binary.
+.Pp
+The maximum size of a core file is limited by
 .Xr setrlimit 2 .
 Files which would be larger than the limit are not created.
 .Pp
-The
-.Nm programname.core
-file consists of the
+The core file consists of the
 .Fa u. area ,
 whose size (in pages) is defined by the
 .Dv UPAGES
@@ -85,13 +101,9 @@
 .Fa user
 structure as given in
 .Aq Pa sys/user.h .
-The remainder of the
-.Nm programname.core
-file consists of the data pages followed by
+The remainder of the core file consists of the data pages followed by
 the stack pages of the process image.
-The amount of data space image in the
-.Nm programname.core
-file is given (in pages) by the
+The amount of data space image in the core file is given (in pages) by the
 variable
 .Fa u_dsize
 in the