lib/libc/gen/auxv.3

   1 .\"
   2 .\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org>
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 16, 2022
  28 .Dt ELF_AUX_INFO 3
  29 .Os
  30 .Sh NAME
  31 .Nm elf_aux_info
  32 .Nd extract data from the elf auxiliary vector of the current process
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In sys/auxv.h
  37 .Ft int
  38 .Fn elf_aux_info "int aux" "void *buf" "int buflen"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn elf_aux_info
  42 function retrieves the auxiliary info vector requested in
  43 .Va aux .
  44 The information is stored into the provided buffer if it will fit.
  45 The following values, defined in
  46 .In sys/elf_common.h
  47 can be requested (corresponding buffer sizes are specified in parenthesis):
  48 .Bl -tag -width AT_OSRELDATE
  49 .It AT_CANARY
  50 The canary value for SSP (arbitrary sized buffer, as many bytes are
  51 returned as it fits into it, rest is zeroed).
  52 .It AT_EXECPATH
  53 The path of executed program
  54 .Dv (MAXPATHLEN).
  55 This may not be present if the process was initialized by
  56 .Xr fexecve 2
  57 and the namecache no longer contains the file's name.
  58 .It AT_HWCAP
  59 CPU / hardware feature flags
  60 .Dv (sizeof(u_long)).
  61 .It AT_HWCAP2
  62 CPU / hardware feature flags
  63 .Dv (sizeof(u_long)).
  64 .It AT_NCPUS
  65 Number of CPUs
  66 .Dv (sizeof(int)).
  67 .It AT_OSRELDATE
  68 The
  69 .Dv OSRELDATE
  70 of the kernel or jail the program is running on
  71 .Dv (sizeof(int)).
  72 .It AT_PAGESIZES
  73 Vector of page sizes (arbitrary sized buffer, as many elements of the
  74 .Dv pagesizes
  75 array are returned as it fits).
  76 .It AT_PAGESZ
  77 Page size in bytes
  78 .Dv (sizeof(int)).
  79 .It AT_TIMEKEEP
  80 Pointer to VDSO timehands (for library internal use,
  81 .Dv sizeof(void *)).
  82 .It AT_USRSTACKBASE
  83 Top of the user stack for main thread.
  84 .It AT_USRSTACKLIM
  85 Limit for grow of the user stack for main thread.
  86 .El
  87 .Sh RETURN VALUES
  88 Returns zero on success, or an error number on failure.
  89 .Sh ERRORS
  90 .Bl -tag -width Er
  91 .It Bq Er EINVAL
  92 An unknown item was requested.
  93 .It Bq Er EINVAL
  94 The provided buffer was not the right size for the requested item.
  95 .It Bq Er ENOENT
  96 The requested item is not available.
  97 .El
  98 .Sh HISTORY
  99 The
 100 .Fn elf_aux_info
 101 function appeared in
 102 .Fx 12.0 .
 103 .Sh BUGS
 104 Only a small subset of available auxiliary info vector items are
 105 accessible with this function.
 106 Some items require a "right-sized" buffer while others just require a
 107 "big enough" buffer.