lib/libelf/elf_cntl.3

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