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 .Dd September 16, 2022
  26 .Dt ELF_AUX_INFO 3
  27 .Os
  28 .Sh NAME
  29 .Nm elf_aux_info
  30 .Nd extract data from the elf auxiliary vector of the current process
  31 .Sh LIBRARY
  32 .Lb libc
  33 .Sh SYNOPSIS
  34 .In sys/auxv.h
  35 .Ft int
  36 .Fn elf_aux_info "int aux" "void *buf" "int buflen"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn elf_aux_info
  40 function retrieves the auxiliary info vector requested in
  41 .Va aux .
  42 The information is stored into the provided buffer if it will fit.
  43 The following values, defined in
  44 .In sys/elf_common.h
  45 can be requested (corresponding buffer sizes are specified in parenthesis):
  46 .Bl -tag -width AT_OSRELDATE
  47 .It AT_CANARY
  48 The canary value for SSP (arbitrary sized buffer, as many bytes are
  49 returned as it fits into it, rest is zeroed).
  50 .It AT_EXECPATH
  51 The path of executed program
  52 .Dv (MAXPATHLEN).
  53 This may not be present if the process was initialized by
  54 .Xr fexecve 2
  55 and the namecache no longer contains the file's name.
  56 .It AT_HWCAP
  57 CPU / hardware feature flags
  58 .Dv (sizeof(u_long)).
  59 .It AT_HWCAP2
  60 CPU / hardware feature flags
  61 .Dv (sizeof(u_long)).
  62 .It AT_NCPUS
  63 Number of CPUs
  64 .Dv (sizeof(int)).
  65 .It AT_OSRELDATE
  66 The
  67 .Dv OSRELDATE
  68 of the kernel or jail the program is running on
  69 .Dv (sizeof(int)).
  70 .It AT_PAGESIZES
  71 Vector of page sizes (arbitrary sized buffer, as many elements of the
  72 .Dv pagesizes
  73 array are returned as it fits).
  74 .It AT_PAGESZ
  75 Page size in bytes
  76 .Dv (sizeof(int)).
  77 .It AT_TIMEKEEP
  78 Pointer to VDSO timehands (for library internal use,
  79 .Dv sizeof(void *)).
  80 .It AT_USRSTACKBASE
  81 Top of the user stack for main thread.
  82 .It AT_USRSTACKLIM
  83 Limit for grow of the user stack for main thread.
  84 .El
  85 .Sh RETURN VALUES
  86 Returns zero on success, or an error number on failure.
  87 .Sh ERRORS
  88 .Bl -tag -width Er
  89 .It Bq Er EINVAL
  90 An unknown item was requested.
  91 .It Bq Er EINVAL
  92 The provided buffer was not the right size for the requested item.
  93 .It Bq Er ENOENT
  94 The requested item is not available.
  95 .El
  96 .Sh HISTORY
  97 The
  98 .Fn elf_aux_info
  99 function appeared in
 100 .Fx 12.0 .
 101 .Sh BUGS
 102 Only a small subset of available auxiliary info vector items are
 103 accessible with this function.
 104 Some items require a "right-sized" buffer while others just require a
 105 "big enough" buffer.