1.\" $NetBSD: elf_flagdata.3,v 1.2 2014/03/09 16:58:04 christos Exp $ 2.\" 3.\" Copyright (c) 2006-2008,2011 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_flagdata.3 2884 2013-01-11 02:03:46Z jkoshy 27.\" 28.Dd December 3, 2011 29.Os 30.Dt ELF_FLAGDATA 3 31.Sh NAME 32.Nm elf_flagarhdr , 33.Nm elf_flagdata , 34.Nm elf_flagehdr , 35.Nm elf_flagelf , 36.Nm elf_flagphdr , 37.Nm elf_flagscn , 38.Nm elf_flagshdr 39.Nd manipulate flags associated with ELF(3) data structures 40.Sh LIBRARY 41.Lb libelf 42.Sh SYNOPSIS 43.In libelf.h 44.Ft "unsigned int" 45.Fn elf_flagarhdr "Elf_Arhdr *arhdr" "Elf_Cmd cmd" "unsigned int flags" 46.Ft "unsigned int" 47.Fn elf_flagdata "Elf_Data *data" "Elf_Cmd cmd" "unsigned int flags" 48.Ft "unsigned int" 49.Fn elf_flagehdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" 50.Ft "unsigned int" 51.Fn elf_flagelf "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" 52.Ft "unsigned int" 53.Fn elf_flagphdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" 54.Ft "unsigned int" 55.Fn elf_flagscn "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags" 56.Ft "unsigned int" 57.Fn elf_flagshdr "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags" 58.Sh DESCRIPTION 59These functions are used to query, set or reset flags on data 60structures associated with an ELF file. 61.Pp 62Arguments 63.Ar arhdr , 64.Ar data , 65.Ar elf 66and 67.Ar scn 68denote the data structures whose flags need to be changed. 69These values should have been returned by prior calls to 70functions in the ELF(3) API set: 71.Bl -bullet -compact 72.It 73Argument 74.Ar arhdr 75should have been returned by a prior call to 76.Xr elf_getarhdr 3 . 77.It 78Argument 79.Ar data 80should have been returned by a prior call to one of 81.Xr elf_newdata 3 , 82.Xr elf_getdata 3 83or 84.Xr elf_rawdata 3 . 85.It 86Argument 87.Ar elf 88should have been allocated by a prior call to one of 89.Xr elf_begin 3 90or 91.Xr elf_memory 3 . 92.It 93Argument 94.Ar scn 95should have been returned by a prior call to one of 96.Xr elf_getscn 3 , 97.Xr elf_newscn 3 98or 99.Xr elf_nextscn 3 . 100.El 101These values are allowed to be NULL to simplify error handling in 102application code. 103.Pp 104Argument 105.Ar cmd 106may have the following values: 107.Bl -tag -width ELF_C_SET 108.It Dv ELF_C_CLR 109The argument 110.Ar flags 111specifies the flags to be cleared. 112.It Dv ELF_C_SET 113The argument 114.Ar flags 115specifies the flags to be set. 116.El 117.Pp 118The argument 119.Ar flags 120is allowed to have the following flags set: 121.Bl -tag -width ELF_F_ARCHIVE_SYSV 122.It Dv ELF_F_ARCHIVE 123This flag is only valid with the 124.Fn elf_flagelf 125API. 126It informs the library that the application desires to create an 127.Xr ar 1 128archive. 129Argument 130.Ar elf 131should have been opened for writing using the 132.Dv ELF_C_WRITE 133command to function 134.Fn elf_begin . 135.It Dv ELF_F_ARCHIVE_SYSV 136This flag is used in conjunction with the 137.Dv ELF_F_ARCHIVE 138flag to indicate that library should create archives that conform 139to System V layout rules. 140The default is to create BSD style archives. 141.It Dv ELF_F_DIRTY 142Mark the associated data structure as needing to be written back 143to the underlying file. 144A subsequent call to 145.Xr elf_update 3 146will resynchronize the library's internal data structures. 147.It Dv ELF_F_LAYOUT 148This flag is only valid with the 149.Fn elf_flagelf 150API. 151It informs the library that the application will take 152responsibility for the layout of the file and that the library is 153not to insert any padding in between sections. 154.El 155.Pp 156Marking a given data structure as 157.Dq dirty 158affects all of its contained elements. 159Thus marking an ELF descriptor 160.Ar elf 161with 162.Fn elf_flagelf "elf" "ELF_C_SET" "ELF_F_DIRTY" 163means that the entire contents of the descriptor are 164.Dq dirty . 165.Pp 166Using a value of zero for argument 167.Ar flags 168will return the current set of flags for the data structure being 169queried. 170.Sh RETURN VALUES 171These functions return the updated flags if successful, or zero if 172an error is detected. 173.Sh COMPATIBILITY 174The 175.Fn elf_flagarhdr 176function and the 177.Dv ELF_F_ARCHIVE 178and 179.Dv ELF_F_ARCHIVE_SYSV 180flags are an extension to the ELF(3) API. 181.Sh ERRORS 182These functions may fail with the following errors: 183.Bl -tag -width "[ELF_E_RESOURCE]" 184.It Bq Er ELF_E_ARGUMENT 185An unsupported value was used for the 186.Ar cmd 187argument. 188.It Bq Er ELF_E_ARGUMENT 189Argument 190.Ar flags 191had unsupported flags set. 192.It Bq Er ELF_E_ARGUMENT 193The argument 194.Ar elf 195was not a descriptor for an ELF object. 196.It Bq Er ELF_E_MODE 197The 198.Dv ELF_F_ARCHIVE 199flag was used with an ELF descriptor that had not been opened for writing. 200.It Bq Er ELF_E_SEQUENCE 201Function 202.Fn elf_flagehdr 203was called without an executable header being allocated. 204.It Bq Er ELF_E_SEQUENCE 205Function 206.Fn elf_flagphdr 207was called without a program header being allocated. 208.El 209.Sh SEE ALSO 210.Xr elf 3 , 211.Xr elf32_newehdr 3 , 212.Xr elf32_newphdr 3 , 213.Xr elf32_newshdr 3 , 214.Xr elf64_newehdr 3 , 215.Xr elf64_newphdr 3 , 216.Xr elf64_newshdr 3 , 217.Xr elf_newdata 3 , 218.Xr elf_update 3 , 219.Xr gelf 3 , 220.Xr gelf_newehdr 3 , 221.Xr gelf_newphdr 3 , 222.Xr gelf_newshdr 3 , 223.Xr gelf_update_dyn 3 , 224.Xr gelf_update_move 3 , 225.Xr gelf_update_rel 3 , 226.Xr gelf_update_rela 3 , 227.Xr gelf_update_sym 3 , 228.Xr gelf_update_syminfo 3 229