1.\" Copyright (c) 2006-2008,2011 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: elf_flagdata.3 3743 2019-06-12 19:36:30Z jkoshy $ 25.\" 26.Dd June 12, 2019 27.Dt ELF_FLAGDATA 3 28.Os 29.Sh NAME 30.Nm elf_flagarhdr , 31.Nm elf_flagdata , 32.Nm elf_flagehdr , 33.Nm elf_flagelf , 34.Nm elf_flagphdr , 35.Nm elf_flagscn , 36.Nm elf_flagshdr 37.Nd manipulate flags associated with ELF data structures 38.Sh LIBRARY 39.Lb libelf 40.Sh SYNOPSIS 41.In libelf.h 42.Ft "unsigned int" 43.Fn elf_flagarhdr "Elf_Arhdr *arhdr" "Elf_Cmd cmd" "unsigned int flags" 44.Ft "unsigned int" 45.Fn elf_flagdata "Elf_Data *data" "Elf_Cmd cmd" "unsigned int flags" 46.Ft "unsigned int" 47.Fn elf_flagehdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" 48.Ft "unsigned int" 49.Fn elf_flagelf "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" 50.Ft "unsigned int" 51.Fn elf_flagphdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" 52.Ft "unsigned int" 53.Fn elf_flagscn "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags" 54.Ft "unsigned int" 55.Fn elf_flagshdr "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags" 56.Sh DESCRIPTION 57These functions are used to query, set or reset flags on data 58structures associated with an ELF file. 59.Pp 60Arguments 61.Ar arhdr , 62.Ar data , 63.Ar elf 64and 65.Ar scn 66denote the data structures whose flags need to be changed. 67These values should have been returned by prior calls to 68functions in the 69.Xr elf 3 70API 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 181.Xr elf 3 182API. 183.Sh ERRORS 184These functions may fail with the following errors: 185.Bl -tag -width "[ELF_E_RESOURCE]" 186.It Bq Er ELF_E_ARGUMENT 187An unsupported value was used for the 188.Ar cmd 189argument. 190.It Bq Er ELF_E_ARGUMENT 191Argument 192.Ar flags 193had unsupported flags set. 194.It Bq Er ELF_E_ARGUMENT 195The argument 196.Ar elf 197was not a descriptor for an ELF object. 198.It Bq Er ELF_E_MODE 199The 200.Dv ELF_F_ARCHIVE 201flag was used with an ELF descriptor that had not been opened for writing. 202.It Bq Er ELF_E_SEQUENCE 203Function 204.Fn elf_flagehdr 205was called without an executable header being allocated. 206.It Bq Er ELF_E_SEQUENCE 207Function 208.Fn elf_flagphdr 209was called without a program header being allocated. 210.El 211.Sh SEE ALSO 212.Xr elf 3 , 213.Xr elf32_newehdr 3 , 214.Xr elf32_newphdr 3 , 215.Xr elf64_newehdr 3 , 216.Xr elf64_newphdr 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_update_dyn 3 , 223.Xr gelf_update_move 3 , 224.Xr gelf_update_rel 3 , 225.Xr gelf_update_rela 3 , 226.Xr gelf_update_sym 3 , 227.Xr gelf_update_syminfo 3 228