coreadm(2)

NAME

coreadm — application core file administration

SYNOPSIS

#include <core.h>

int coreadm(int c_version, pid_t c_pid, core_file_settings_t *c_in, core_file_settings_t *c_out);

DESCRIPTION

coreadm() system call is used to specify the location and pattern for core files produced by abnormally terminating processes. See core(4). This system call can be used to specify a system wide location for core file placement and/or a process specific pattern.

The structure, corefile_settings_t is used to specify a system wide or a per-process core file pattern and also specify the current system wide core file settings. corefile_settings_t is defined in the header <core.h>.

Member Type	Member Name	Description
`char`	`c_pattern`	The core file pattern.
`uint64_t`	`c_flags`	Core file settings.

Parameters

c_version is expected to be set to COREADM_VERSION. It is critical for future backward compatibility that the COREADM_VERSION macro itself be used and not its value.

c_pattern is the core file pattern. A core file name pattern is a normal file system path name with embedded variables, specified with a leading % character, that are expanded from values in effect when a core file is generated by the operating system. An expanded pattern length greater than MAXPATHLEN will be truncated to MAXPATHLEN.

The possible values are:

%p   process ID
%xp  Process ID in hex
%u   effective user-ID
%xu  effective user-ID in Hex
%g   effective group-ID
%xg  effective group-ID in Hex
%c   thread's CPU number when the core file was created
%f   executable file name, up to a maximum of MAXCOMMLEN characters
%n   system node name (uname -n)
%t   time-stamp (in UTC time format)
%%   literal %

c_flags is used to control the system wide core file settings. The flag values can be combination of

COREADM_GLBL_ENABLED: Enable/Disable creation of global core files.
COREADM_PROC_ENABLED: Enable/Disable creation of per-process core files.
COREADM_GLBL_SETID_ENABLED: Enable/Disable creation of global core files for setuid processes.
COREADM_PROC_SETID_ENABLED: Enable/Disable creation of per-process core file for setuid processes.

If a flag value is not set, then the option is disabled.

For per-process core file setting, c_flags can either be 0 or COREADM_PROC_ENABLED. The former disables core file creation (for that process) and the latter enables it.

c_pid: Should be a (valid) pid of a target process or 0. If c_pid is zero, then the settings are applied to global core file settings. If c_pid is 1, then the settings are applied to init(1M).
c_in: If non-NULL, then the values will be used as new core file settings. If this is NULL, then the c_out parameter is expected to be non-NULL and system call is used to interrogate the current settings.
c_out: If non-NULL, the current settings are returned in this parameter.

RETURN VALUE

Upon successful completion, coreadm() returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.

ERRORS

EPERM: coreadm() fails and does not change the core file settings if the effective user-ID of the calling process is not a user having appropriate privileges.
EFAULT: The input or output parameter passed to coreadm() is an invalid address.
EINVAL: The core file pattern or flags is invalid.
ESRCH: The specified PID is non-zero and does not exist.

EXAMPLES

1.: Enable global core file creation using the pattern (core.process-ID.machine-name) in the location /mnt/cores.

#include <stdio.h> 
#include <stdlib.h> 
#include <errno.h> 
#include <limits.h> 
#include <sys/types.h> 
#include <sys/core.h> 

main() 
{ 
   corefile_settings_t c_in, c_out; 
   int   ret; 

   bzero(&c_in, sizeof(c_in)); 
   bzero(&c_out,sizeof(c_out)); 

   /* Read the current settings. */ 
   ret = coreadm(COREADM_VERSION, (pid_t)0, \ 
         (corefile_settings_t *) NULL, &c_out); 
   if (ret) { 
      perror("coreadm"); 
      exit(ret); 
   } 

   /* Setup new core settings. */ 
   strcpy(c_in.c_pattern,"/mnt/cores/core.%p.%n"); 
   c_in.c_flags = c_out.c_flags | COREADM_GLOB_ENABLED; 

   /* Set the new values. */ 
   ret = coreadm(COREADM_VERSION, (pid_t)0, &c_in, &c_out); 
   if (ret) { 
      perror("coreadm"); 
      exit(ret); 
   } 
} 

2.: Enable per-process core file pattern for the process-ID passed in as argument. The core file will be placed in PWD/corefle. The pattern is (core.process-ID.time-stamp).

#include <stdio.h> 
#include <stdlib.h> 
#include <errno.h> 
#include <sys/param.h> 
#include <sys/core.h> 
#include <sys/types.h> 
#include <string.h> 

main(int argc, char **argv) 
{ 
   corefile_settings_t  c_in, c_out; 
   int           ret; 

   if (argc < 2) { 
      fprintf(stderr,"Usage %s <PID>\n", argv[0]); 
      exit(2); 
   } 

   bzero(&c_in, sizeof(c_in)); 
   bzero(&c_out,sizeof(c_out)); 

   strcpy(c_in.c_pattern,"core.%p.%t"); 
   c_in.c_flags = COREADM_PROC_ENABLED; 

   /* Read the current settings. */ 
   ret = coreadm(COREADM_VERSION, (pid_t)0, \ 
         (corefile_settings_t *) NULL, &c_out); 
   if (ret) { 
      perror("coreadm"); 
      exit(ret); 
   } 

   if ((c_out.c_flags & COREADM_PROC_ENABLED) == 0) { 
      fprintf(stdout, 
         "Warning: System wide Per-process core file dumping\ 
           currently disabled."); 
   } 

   /* Set the new values. */ 
   ret = coreadm(COREADM_VERSION, strtol(argv[1], (char **)NULL, 10),\ 
         &c_in, &c_out); 
   if (ret) { 
      perror("coreadm"); 
      exit(ret); 
   } 
} 

3.: Enable a per-process pattern of core.CUP-ID for all processes in the system ( init(1M) core file setting). NOTE: This has to be run during system startup or reboot the machine after setting this for the settings to take full effect.

#include <stdio.h> 
#include <stdlib.h> 
#include <errno.h> 
#include <sys/param.h> 
#include <sys/core.h> 
#include <sys/types.h> 
#include <string.h> 

main(int argc, char **argv) 
{ 
   corefile_settings_t  c_in, c_out; 
   int           ret; 

   bzero(&c_in, sizeof(c_in)); 
   bzero(&c_out,sizeof(c_out)); 
   strcpy(c_in.c_pattern, "core.%c"); 
   c_in.c_flags   = COREADM_PROC_ENABLED; 

   /* Read the current settings. */ 
   ret = coreadm(COREADM_VERSION, (pid_t)0, \ 
         (corefile_settings_t *) NULL, &c_out); 
   if (ret) { 
      perror("coreadm"); 
      exit(ret); 
   } 

   if ((c_out.c_flags & COREADM_PROC_ENABLED) == 0) { 
      /* If core file creation is disabled, enable it. */ 
      bcopy(&c_out, &c_in, sizeof c_out); 
      c_in.c_flags |= COREADM_PROC_ENABLED; 
      ret = coreadm(COREADM_VERSION, 0, &c_in,\ 
            (corefile_settings_t *)NULL); 
   } 

   /* Set the new values. */ 
   ret = coreadm(COREADM_VERSION, 1 , &c_in, &c_out); 
   if (ret) { 
      perror("coreadm"); 
      exit(ret); 
   } 
} 

STANDARDS CONFORMANCE

coreadm(): AES, SVID2, SVID3, XPG2, XPG3, XPG4

coreadm(2)

Technical documentation

» Table of Contents

» Index