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