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 3479 2016-06-25 20:44:33Z jkoshy $ 25.\" 26.Dd December 3, 2011 27.Os 28.Dt ELF_FLAGDATA 3 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(3) 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 ELF(3) API set: 69.Bl -bullet -compact 70.It 71Argument 72.Ar arhdr 73should have been returned by a prior call to 74.Xr elf_getarhdr 3 . 75.It 76Argument 77.Ar data 78should have been returned by a prior call to one of 79.Xr elf_newdata 3 , 80.Xr elf_getdata 3 81or 82.Xr elf_rawdata 3 . 83.It 84Argument 85.Ar elf 86should have been allocated by a prior call to one of 87.Xr elf_begin 3 88or 89.Xr elf_memory 3 . 90.It 91Argument 92.Ar scn 93should have been returned by a prior call to one of 94.Xr elf_getscn 3 , 95.Xr elf_newscn 3 96or 97.Xr elf_nextscn 3 . 98.El 99These values are allowed to be NULL to simplify error handling in 100application code. 101.Pp 102Argument 103.Ar cmd 104may have the following values: 105.Bl -tag -width ELF_C_SET 106.It Dv ELF_C_CLR 107The argument 108.Ar flags 109specifies the flags to be cleared. 110.It Dv ELF_C_SET 111The argument 112.Ar flags 113specifies the flags to be set. 114.El 115.Pp 116The argument 117.Ar flags 118is allowed to have the following flags set: 119.Bl -tag -width ELF_F_ARCHIVE_SYSV 120.It Dv ELF_F_ARCHIVE 121This flag is only valid with the 122.Fn elf_flagelf 123API. 124It informs the library that the application desires to create an 125.Xr ar 1 126archive. 127Argument 128.Ar elf 129should have been opened for writing using the 130.Dv ELF_C_WRITE 131command to function 132.Fn elf_begin . 133.It Dv ELF_F_ARCHIVE_SYSV 134This flag is used in conjunction with the 135.Dv ELF_F_ARCHIVE 136flag to indicate that library should create archives that conform 137to System V layout rules. 138The default is to create BSD style archives. 139.It Dv ELF_F_DIRTY 140Mark the associated data structure as needing to be written back 141to the underlying file. 142A subsequent call to 143.Xr elf_update 3 144will resynchronize the library's internal data structures. 145.It Dv ELF_F_LAYOUT 146This flag is only valid with the 147.Fn elf_flagelf 148API. 149It informs the library that the application will take 150responsibility for the layout of the file and that the library is 151not to insert any padding in between sections. 152.El 153.Pp 154Marking a given data structure as 155.Dq dirty 156affects all of its contained elements. 157Thus marking an ELF descriptor 158.Ar elf 159with 160.Fn elf_flagelf "elf" "ELF_C_SET" "ELF_F_DIRTY" 161means that the entire contents of the descriptor are 162.Dq dirty . 163.Pp 164Using a value of zero for argument 165.Ar flags 166will return the current set of flags for the data structure being 167queried. 168.Sh RETURN VALUES 169These functions return the updated flags if successful, or zero if 170an error is detected. 171.Sh COMPATIBILITY 172The 173.Fn elf_flagarhdr 174function and the 175.Dv ELF_F_ARCHIVE 176and 177.Dv ELF_F_ARCHIVE_SYSV 178flags are an extension to the ELF(3) API. 179.Sh ERRORS 180These functions may fail with the following errors: 181.Bl -tag -width "[ELF_E_RESOURCE]" 182.It Bq Er ELF_E_ARGUMENT 183An unsupported value was used for the 184.Ar cmd 185argument. 186.It Bq Er ELF_E_ARGUMENT 187Argument 188.Ar flags 189had unsupported flags set. 190.It Bq Er ELF_E_ARGUMENT 191The argument 192.Ar elf 193was not a descriptor for an ELF object. 194.It Bq Er ELF_E_MODE 195The 196.Dv ELF_F_ARCHIVE 197flag was used with an ELF descriptor that had not been opened for writing. 198.It Bq Er ELF_E_SEQUENCE 199Function 200.Fn elf_flagehdr 201was called without an executable header being allocated. 202.It Bq Er ELF_E_SEQUENCE 203Function 204.Fn elf_flagphdr 205was called without a program header being allocated. 206.El 207.Sh SEE ALSO 208.Xr elf 3 , 209.Xr elf32_newehdr 3 , 210.Xr elf32_newphdr 3 , 211.Xr elf64_newehdr 3 , 212.Xr elf64_newphdr 3 , 213.Xr elf_newdata 3 , 214.Xr elf_update 3 , 215.Xr gelf 3 , 216.Xr gelf_newehdr 3 , 217.Xr gelf_newphdr 3 , 218.Xr gelf_update_dyn 3 , 219.Xr gelf_update_move 3 , 220.Xr gelf_update_rel 3 , 221.Xr gelf_update_rela 3 , 222.Xr gelf_update_sym 3 , 223.Xr gelf_update_syminfo 3 224