share/man/man3elf/elf_version.3elf

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH ELF_VERSION 3ELF "Jul 11, 2001"
   7 .SH NAME
   8 elf_version \- coordinate ELF library and application versions
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
  13 #include <libelf.h>
  14
  15 \fBunsigned\fR \fBelf_version\fR(\fBunsigned\fR \fIver\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 As \fBelf\fR(3ELF) explains, the program, the library, and an object file have
  22 independent notions of the latest \fBELF\fR version. \fBelf_version()\fR lets a
  23 program query the \fBELF\fR library's \fIinternal version\fR. It further lets
  24 the program specify what memory types it uses by giving its own \fIworking
  25 version\fR, \fBver\fR, to the library. Every program that uses the \fBELF\fR
  26 library must coordinate versions as described below.
  27 .sp
  28 .LP
  29 The header <\fBlibelf.h\fR> supplies the version to the program with the macro
  30 \fBEV_CURRENT\fR. If the library's internal version (the highest version known
  31 to the library) is lower than that known by the program itself, the library may
  32 lack semantic knowledge assumed by the program. Accordingly,
  33 \fBelf_version()\fR will not accept a working version unknown to the library.
  34 .sp
  35 .LP
  36 Passing \fIver\fR equal to \fBEV_NONE\fR causes \fBelf_version()\fR to return
  37 the library's internal version, without altering the working version. If
  38 \fBver\fR is a version known to the library, \fBelf_version()\fR returns the
  39 previous (or initial) working version number. Otherwise, the working version
  40 remains unchanged and \fBelf_version()\fR returns \fBEV_NONE\fR.
  41 .SH EXAMPLES
  42 .LP
  43 \fBExample 1 \fRA sample display of using the \fBelf_version()\fR function.
  44 .sp
  45 .LP
  46 The following excerpt from an application program protects itself from using an
  47 older library:
  48
  49 .sp
  50 .in +2
  51 .nf
  52 \fBif (elf_version(EV_CURRENT) == EV_NONE) {
  53         /* library out of date */
  54         /* recover from error */
  55 }\fR
  56 .fi
  57 .in -2
  58
  59 .SH ATTRIBUTES
  60 .sp
  61 .LP
  62 See \fBattributes\fR(5) for descriptions of the following attributes:
  63 .sp
  64
  65 .sp
  66 .TS
  67 box;
  68 c | c
  69 l | l .
  70 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  71 _
  72 Interface Stability     Stable
  73 _
  74 MT-Level        MT-Safe
  75 .TE
  76
  77 .SH SEE ALSO
  78 .sp
  79 .LP
  80 \fBelf\fR(3ELF), \fBelf32_xlatetof\fR(3ELF), \fBelf_begin\fR(3ELF),
  81 \fBlibelf\fR(3LIB), \fBattributes\fR(5)
  82 .SH NOTES
  83 .sp
  84 .LP
  85 The working version should be the same for all operations on a particular
  86 \fBELF\fR descriptor. Changing the version between operations on a descriptor
  87 will probably not give the expected results.