external/bsd/elftoolchain/dist/libelf/elf_cntl.3

   1 .\"     $NetBSD: elf_cntl.3,v 1.2 2014/03/09 16:58:04 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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 Joseph Koshy ``as is'' and
  15 .\" any express or implied warranties, including, but not limited to, the
  16 .\" implied warranties of merchantability and fitness for a particular purpose
  17 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  18 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  19 .\" damages (including, but not limited to, procurement of substitute goods
  20 .\" or services; loss of use, data, or profits; or business interruption)
  21 .\" however caused and on any theory of liability, whether in contract, strict
  22 .\" liability, or tort (including negligence or otherwise) arising in any way
  23 .\" out of the use of this software, even if advised of the possibility of
  24 .\" such damage.
  25 .\"
  26 .\" Id: elf_cntl.3 289 2009-01-08 08:26:08Z jkoshy
  27 .\"
  28 .Dd August 9, 2006
  29 .Os
  30 .Dt ELF_CNTL 3
  31 .Sh NAME
  32 .Nm elf_cntl
  33 .Nd control an elf file descriptor
  34 .Sh LIBRARY
  35 .Lb libelf
  36 .Sh SYNOPSIS
  37 .In libelf.h
  38 .Ft int
  39 .Fn elf_cntl "Elf *elf" "Elf_Cmd cmd"
  40 .Sh DESCRIPTION
  41 Function
  42 .Fn elf_cntl
  43 controls the ELF library's subsequent use of the file descriptor
  44 used to create ELF descriptor
  45 .Ar elf .
  46 .Pp
  47 Argument
  48 .Ar cmd
  49 informs the library of the action to be taken:
  50 .Bl -tag -width "ELF_C_FDDONE"
  51 .It Dv ELF_C_FDDONE
  52 This value instructs the ELF library not to perform any further
  53 I/O on the file descriptor associated with argument
  54 .Ar elf .
  55 For ELF descriptors opened with mode
  56 .Ar ELF_C_WRITE
  57 or
  58 .Ar ELF_C_RDWR
  59 subsequent
  60 .Fn elf_update
  61 operations on the descriptor will fail.
  62 .It Dv ELF_C_FDREAD
  63 This value instructs the ELF library to read in all necessary
  64 data associated with ELF descriptor
  65 .Ar elf
  66 into memory so that the underlying file descriptor can be
  67 safely closed with command
  68 .Dv ELF_C_FDDONE .
  69 .El
  70 .Pp
  71 Argument
  72 .Ar elf
  73 must be an ELF descriptor associated with a file system object
  74 (e.g., an
  75 .Xr ar 1
  76 archive, an ELF file, or other data file).
  77 .Sh IMPLEMENTATION NOTES
  78 Due to use of
  79 .Xr mmap 2
  80 internally, this function is a no-op for ELF objects opened in
  81 .Dv ELF_C_READ
  82 mode.
  83 .Sh RETURN VALUES
  84 Function
  85 .Fn elf_cntl
  86 returns 0 on success, or -1 if an error was detected.
  87 .Sh ERRORS
  88 .Bl -tag -width "[ELF_E_RESOURCE]"
  89 .It Bq Er ELF_E_ARCHIVE
  90 Argument
  91 .Ar elf
  92 is a descriptor for an archive member.
  93 .It Bq Er ELF_E_ARGUMENT
  94 Argument
  95 .Ar elf
  96 was NULL.
  97 .It Bq Er ELF_E_ARGUMENT
  98 Argument
  99 .Ar cmd
 100 was not recognized.
 101 .It Bq Er ELF_E_MODE
 102 An
 103 .Dv ELF_C_FDREAD
 104 operation was requested on an ELF descriptor opened
 105 for writing.
 106 .El
 107 .Sh SEE ALSO
 108 .Xr elf 3 ,
 109 .Xr elf_begin 3 ,
 110 .Xr elf_end 3 ,
 111 .Xr elf_next 3 ,
 112 .Xr elf_update 3 ,
 113 .Xr gelf 3