1 EFI_ALLOC_AND_INIT(3EXT) Extended Library Functions EFI_ALLOC_AND_INIT(3EXT) 2 3 4 5 NAME 6 efi_alloc_and_init, efi_alloc_and_read, efi_free, efi_write, 7 efi_use_whole_disk, efi_reserved_sectors - manipulate a disk's EFI 8 Partition Table 9 10 SYNOPSIS 11 cc [ flag ... ] file... -lefi [ library ... ] 12 #include <sys/vtoc.h> 13 #include <sys/efi_partition.h> 14 15 int efi_alloc_and_init(int fd, uint32_t nparts, dk_gpt_t **vtoc); 16 17 18 int efi_alloc_and_read(int fd, dk_gpt_t **vtoc); 19 20 21 void efi_free(dk_gpt_t *vtoc); 22 23 24 int efi_write(int fd, dk_gpt_t *vtoc); 25 26 27 int efi_use_whole_disk(int fd); 28 29 30 uint_t efi_reserved_sectors(dk_gpt_t *vtoc); 31 32 33 DESCRIPTION 34 The efi_alloc_and_init() function initializes the dk_gpt_t structure 35 specified by vtoc in preparation for a call to efi_write(). It 36 calculates and initializes the efi_version, efi_lbasize, efi_nparts, 37 efi_first_u_lba, efi_last_lba, and efi_last_u_lba members of this 38 structure. The caller can then set the efi_nparts member. 39 40 41 The efi_alloc_and_read() function allocates memory and returns the 42 partition table. 43 44 45 The efi_free() function frees the memory allocated by 46 efi_alloc_and_init() and efi_alloc_and_read(). 47 48 49 The efi_write() function writes the EFI partition table and creates a 50 Protective Master Boot Record (PMBR); see below. 51 52 53 The efi_use_whole_disk() function takes any space that is not contained 54 in the disk label and adds it to the last physically non-zero area 55 before the reserved slice (from slice 0 to slice 6 or unallocated 56 space). 57 58 59 The efi_reserved_sectors() function calculates number of sectors needed 60 to create the reserved partition. The reserved partition is used by the 61 operating system for internal purposes. The sector size used is based 62 on the device and is recorded in the efi_lbasize member of the dkgpt_t 63 structure indicated by the vtoc argument. A full description of the 64 dk_gpt_t structure appears later in the manual. 65 66 67 The fd argument refers to any slice on a raw disk, opened with 68 O_NDELAY. See open(2). 69 70 71 The nparts argument specifies the number of desired partitions. 72 73 74 The vtoc argument is a dk_gpt_t structure that describes an EFI 75 partition table and contains at least the following members: 76 77 uint_t efi_version; /* set to EFI_VERSION_CURRENT */ 78 uint_t efi_nparts; /* no. of partitions in efi_parts */ 79 uint_t efi_lbasize; /* size of block in bytes */ 80 diskaddr_t efi_last_lba; /* last block on the disk */ 81 diskaddr_t efi_first_u_lba; /* first block after labels */ 82 diskaddr_t efi_last_u_lba; /* last block before backup labels */ 83 struct dk_part efi_parts[]; /* array of partitions */ 84 85 86 Protective Master Boot Record 87 When a disk receives an EFI label, a protective MBR (PMBR) is also 88 written containing a single partition of type EEh and spanning the 89 entire disk (up to the limit of what can be represented in an MBR). By 90 default that partition is placed in slot 0 of the PMBR and not marked 91 as active. Some BIOS implementations contain bugs that require the 92 entry to be placed into a different slot or to be made active in order 93 for the system to boot successfully. The default behaviour is modified 94 for systems with known firmware bugs, refer to 95 /usr/share/hwdata/efi.fixes for more information. 96 97 98 RETURN VALUES 99 Upon successful completion, efi_alloc_and_init() returns 0. Otherwise 100 it returns VT_EIO if an I/O operation to the disk fails. 101 102 103 Upon successful completion, efi_alloc_and_read() returns a positive 104 integer indicating the slice index associated with the open file 105 descriptor. Otherwise, it returns a negative integer to indicate one 106 of the following: 107 108 VT_EIO 109 An I/O error occurred. 110 111 112 VT_ERROR 113 An unknown error occurred. 114 115 116 VT_EINVAL 117 An EFI label was not found. 118 119 120 121 The efi_reserved_sectors() function always returns the number of 122 reserved sectors required. It will always succeed. 123 124 125 126 Upon successful completion, efi_write() returns 0. Otherwise, it 127 returns a negative integer to indicate one of the following: 128 129 VT_EIO 130 An I/O error occurred. 131 132 133 VT_ERROR 134 An unknown error occurred. 135 136 137 VT_EINVAL 138 The label contains incorrect data. 139 140 141 142 Upon successfully completion, efi_use_whole_disk() returns 0. 143 Otherwise, it returns a negative integer to indicate one of the 144 following: 145 146 VT_EIO 147 An I/O error occurred. 148 149 150 VT_ERROR 151 An unknown error occurred. 152 153 154 VT_EINVAL 155 The label contains incorrect data. 156 157 158 VT_ENOSPC 159 Space out of label was not found. 160 161 162 USAGE 163 The EFI label is used on disks with more than 1^32-1 blocks. For 164 compatibility reasons, the read_vtoc(3EXT) and write_vtoc() functions 165 should be used on smaller disks. The application should attempt the 166 read_vtoc() or write_vtoc() call, check for an error of VT_ENOTSUP, 167 then call the analogous EFI function. 168 169 ATTRIBUTES 170 See attributes(5) for descriptions of the following attributes: 171 172 173 174 175 +--------------------+-----------------+ 176 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 177 +--------------------+-----------------+ 178 |Interface Stability | Committed | 179 +--------------------+-----------------+ 180 |MT-Level | Unsafe | 181 +--------------------+-----------------+ 182 183 SEE ALSO 184 fmthard(1M), format(1M), prtvtoc(1M), ioctl(2), open(2), libefi(3LIB), 185 read_vtoc(3EXT), attributes(5), dkio(7I) 186 187 188 189 May 16, 2020 EFI_ALLOC_AND_INIT(3EXT)