libzbc
Data Structures | Macros | Enumerations | Functions
Libzbc

Data Structures

struct  zbc_zone
 Zone information data structure. More...
 
struct  zbc_device_info
 Device information data structure. More...
 
struct  zbc_errno
 Detailed error information data structure. More...
 

Macros

#define zbc_zone_type(z)   ((int)(z)->zbz_type)
 Get a zone type.
 
#define zbc_zone_conventional(z)   ((z)->zbz_type == ZBC_ZT_CONVENTIONAL)
 Test if a zone type is conventional.
 
#define zbc_zone_sequential_req(z)   ((z)->zbz_type == ZBC_ZT_SEQUENTIAL_REQ)
 Test if a zone type is sequential write required.
 
#define zbc_zone_sequential_pref(z)   ((z)->zbz_type == ZBC_ZT_SEQUENTIAL_PREF)
 Test if a zone type is sequential write preferred.
 
#define zbc_zone_sequential(z)
 Test if a zone type is sequential write required or preferred. More...
 
#define zbc_zone_condition(z)   ((int)(z)->zbz_condition)
 Get a zone condition.
 
#define zbc_zone_not_wp(z)   ((z)->zbz_condition == ZBC_ZC_NOT_WP)
 Test if a zone condition is "not write pointer zone".
 
#define zbc_zone_empty(z)   ((z)->zbz_condition == ZBC_ZC_EMPTY)
 Test if a zone condition is empty.
 
#define zbc_zone_imp_open(z)   ((z)->zbz_condition == ZBC_ZC_IMP_OPEN)
 Test if a zone condition is implicit open.
 
#define zbc_zone_exp_open(z)   ((z)->zbz_condition == ZBC_ZC_EXP_OPEN)
 Test if a zone condition is explicit open.
 
#define zbc_zone_is_open(z)
 Test if a zone condition is explicit or implicit open. More...
 
#define zbc_zone_closed(z)   ((z)->zbz_condition == ZBC_ZC_CLOSED)
 Test if a zone condition is closed.
 
#define zbc_zone_full(z)   ((z)->zbz_condition == ZBC_ZC_FULL)
 Test if a zone condition is full.
 
#define zbc_zone_rdonly(z)   ((z)->zbz_condition == ZBC_ZC_RDONLY)
 Test if a zone condition is read-only.
 
#define zbc_zone_offline(z)   ((z)->zbz_condition == ZBC_ZC_OFFLINE)
 Test if a zone condition is offline.
 
#define zbc_zone_rwp_recommended(z)
 Test if a zone has the reset recommended flag set. More...
 
#define zbc_zone_non_seq(z)   ((z)->zbz_attributes & ZBC_ZA_NON_SEQ)
 Test if a zone has the non sequential write resource allocated flag set.
 
#define zbc_zone_start(z)   ((unsigned long long)(z)->zbz_start)
 Get a zone start 512B sector.
 
#define zbc_zone_length(z)   ((unsigned long long)(z)->zbz_length)
 Get a zone number of 512B sectors.
 
#define zbc_zone_wp(z)   ((unsigned long long)(z)->zbz_write_pointer)
 Get a zone write pointer 512B sector position.
 
#define ZBC_DEVICE_INFO_LENGTH   32
 
#define ZBC_NOT_REPORTED   ((uint32_t)0xFFFFFFFF)
 
#define ZBC_NO_LIMIT   ((uint32_t)0xFFFFFFFF)
 
#define zbc_lba2sect(info, lba)   (((lba) * (info)->zbd_lblock_size) >> 9)
 Convert LBA value to 512-bytes sector. More...
 
#define zbc_sect2lba(info, sect)   (((sect) << 9) / (info)->zbd_lblock_size)
 Convert 512-bytes sector value to LBA. More...
 

Enumerations

enum  zbc_zone_type { ZBC_ZT_UNKNOWN = 0x00, ZBC_ZT_CONVENTIONAL = 0x01, ZBC_ZT_SEQUENTIAL_REQ = 0x02, ZBC_ZT_SEQUENTIAL_PREF = 0x03 }
 Zone type definitions. More...
 
enum  zbc_zone_condition {
  ZBC_ZC_NOT_WP = 0x00, ZBC_ZC_EMPTY = 0x01, ZBC_ZC_IMP_OPEN = 0x02, ZBC_ZC_EXP_OPEN = 0x03,
  ZBC_ZC_CLOSED = 0x04, ZBC_ZC_RDONLY = 0x0d, ZBC_ZC_FULL = 0x0e, ZBC_ZC_OFFLINE = 0x0f
}
 Zone condition definitions. More...
 
enum  zbc_zone_attributes { ZBC_ZA_RWP_RECOMMENDED = 0x0001, ZBC_ZA_NON_SEQ = 0x0002 }
 Zone attributes definitions. More...
 
enum  zbc_dev_type {
  ZBC_DT_UNKNOWN = 0x00, ZBC_DT_BLOCK = 0x01, ZBC_DT_SCSI = 0x02, ZBC_DT_ATA = 0x03,
  ZBC_DT_FAKE = 0x04
}
 Device type definitions. More...
 
enum  zbc_dev_model {
  ZBC_DM_DRIVE_UNKNOWN = 0x00, ZBC_DM_HOST_AWARE = 0x01, ZBC_DM_HOST_MANAGED = 0x02, ZBC_DM_DEVICE_MANAGED = 0x03,
  ZBC_DM_STANDARD = 0x04
}
 Device model definitions. More...
 
enum  zbc_dev_flags { ZBC_UNRESTRICTED_READ = 0x00000001 }
 Device flags definitions. More...
 
enum  zbc_sk {
  ZBC_SK_NOT_READY = 0x2, ZBC_SK_MEDIUM_ERROR = 0x3, ZBC_SK_ILLEGAL_REQUEST = 0x5, ZBC_SK_DATA_PROTECT = 0x7,
  ZBC_SK_ABORTED_COMMAND = 0xB
}
 SCSI Sense keys definitions. More...
 
enum  zbc_asc_ascq {
  ZBC_ASC_INVALID_FIELD_IN_CDB = 0x2400, ZBC_ASC_LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE = 0x2100, ZBC_ASC_UNALIGNED_WRITE_COMMAND = 0x2104, ZBC_ASC_WRITE_BOUNDARY_VIOLATION = 0x2105,
  ZBC_ASC_ATTEMPT_TO_READ_INVALID_DATA = 0x2106, ZBC_ASC_READ_BOUNDARY_VIOLATION = 0x2107, ZBC_ASC_ZONE_IS_READ_ONLY = 0x2708, ZBC_ASC_INSUFFICIENT_ZONE_RESOURCES = 0x550E,
  ZBC_ASC_READ_ERROR = 0x1100, ZBC_ASC_WRITE_ERROR = 0x0C00, ZBC_ASC_FORMAT_IN_PROGRESS = 0x0404
}
 SCSI Additional sense codes and qualifiers definitions. More...
 
enum  zbc_oflags { ZBC_O_DRV_BLOCK = 0x01000000, ZBC_O_DRV_SCSI = 0x02000000, ZBC_O_DRV_ATA = 0x04000000, ZBC_O_DRV_FAKE = 0x08000000 }
 ZBC device open flags. More...
 
enum  zbc_reporting_options {
  ZBC_RO_ALL = 0x00, ZBC_RO_EMPTY = 0x01, ZBC_RO_IMP_OPEN = 0x02, ZBC_RO_EXP_OPEN = 0x03,
  ZBC_RO_CLOSED = 0x04, ZBC_RO_FULL = 0x05, ZBC_RO_RDONLY = 0x06, ZBC_RO_OFFLINE = 0x07,
  ZBC_RO_RWP_RECOMMENDED = 0x10, ZBC_RO_NON_SEQ = 0x11, ZBC_RO_NOT_WP = 0x3f, ZBC_RO_PARTIAL = 0x80
}
 Reporting options definitions. More...
 
enum  zbc_zone_op { ZBC_OP_RESET_ZONE = 0x01, ZBC_OP_OPEN_ZONE = 0x02, ZBC_OP_CLOSE_ZONE = 0x03, ZBC_OP_FINISH_ZONE = 0x04 }
 Zone operation codes definitions. More...
 
enum  zbc_zone_op_flags { ZBC_OP_ALL_ZONES = 0x0000001 }
 Zone operation flag definitions. More...
 

Functions

void zbc_set_log_level (char const *log_level)
 Set the library log level. More...
 
const char * zbc_zone_type_str (enum zbc_zone_type type)
 returns a string describing a zone type More...
 
const char * zbc_zone_condition_str (enum zbc_zone_condition cond)
 Returns a string describing a zone condition. More...
 
const char * zbc_device_type_str (enum zbc_dev_type type)
 Returns a device type name. More...
 
const char * zbc_device_model_str (enum zbc_dev_model model)
 Returns a device zone model name. More...
 
void zbc_errno (struct zbc_device *dev, struct zbc_errno *err)
 Get detailed error code of last operation. More...
 
const char * zbc_sk_str (enum zbc_sk sk)
 Returns a string describing a sense key. More...
 
const char * zbc_asc_ascq_str (enum zbc_asc_ascq asc_ascq)
 Returns a string describing a sense code. More...
 
int zbc_device_is_zoned (const char *filename, bool fake, struct zbc_device_info *info)
 Test if a device is a zoned block device. More...
 
int zbc_open (const char *filename, int flags, struct zbc_device **dev)
 Open a ZBC device. More...
 
int zbc_close (struct zbc_device *dev)
 Close a ZBC device. More...
 
void zbc_get_device_info (struct zbc_device *dev, struct zbc_device_info *info)
 Get a ZBC device information. More...
 
void zbc_print_device_info (struct zbc_device_info *info, FILE *out)
 Print a device information. More...
 
int zbc_report_zones (struct zbc_device *dev, uint64_t sector, enum zbc_reporting_options ro, struct zbc_zone *zones, unsigned int *nr_zones)
 Get zone information. More...
 
int zbc_list_zones (struct zbc_device *dev, uint64_t sector, enum zbc_reporting_options ro, struct zbc_zone **zones, unsigned int *nr_zones)
 Get zone information. More...
 
int zbc_zone_operation (struct zbc_device *dev, uint64_t sector, enum zbc_zone_op op, unsigned int flags)
 Execute an operation on a zone. More...
 
ssize_t zbc_pread (struct zbc_device *dev, void *buf, size_t count, uint64_t offset)
 Read sectors form a device. More...
 
ssize_t zbc_pwrite (struct zbc_device *dev, const void *buf, size_t count, uint64_t offset)
 Write sectors to a device. More...
 
ssize_t zbc_preadv (struct zbc_device *dev, const struct iovec *iov, int iovcnt, uint64_t offset)
 Read sectors from a device using mutliple buffers. More...
 
ssize_t zbc_pwritev (struct zbc_device *dev, const struct iovec *iov, int iovcnt, uint64_t offset)
 Write sectors to a device unsig multiple buffers. More...
 
int zbc_map_iov (const void *buf, size_t sectors, struct iovec *iov, int iovcnt, size_t iovlen)
 Map a buffer to an I/O vector. More...
 
int zbc_flush (struct zbc_device *dev)
 Flush a device write cache. More...
 

Detailed Description

Macro Definition Documentation

#define ZBC_DEVICE_INFO_LENGTH   32

Vendor ID string maximum length.

#define zbc_lba2sect (   info,
  lba 
)    (((lba) * (info)->zbd_lblock_size) >> 9)

Convert LBA value to 512-bytes sector.

Returns
A number of 512B sectors.
#define ZBC_NO_LIMIT   ((uint32_t)0xFFFFFFFF)

"no limit" value for the number of explicitly open sequential write required zones in the device information (zbd_max_nr_open_seq_req).

#define ZBC_NOT_REPORTED   ((uint32_t)0xFFFFFFFF)

"not reported" value for the number of zones limits in the device information (zbd_opt_nr_non_seq_write_seq_pref and zbd_max_nr_open_seq_req).

#define zbc_sect2lba (   info,
  sect 
)    (((sect) << 9) / (info)->zbd_lblock_size)

Convert 512-bytes sector value to LBA.

Returns
A number of logical blocks.
#define zbc_zone_is_open (   z)
Value:
#define zbc_zone_exp_open(z)
Test if a zone condition is explicit open.
Definition: zbc.h:266
#define zbc_zone_imp_open(z)
Test if a zone condition is implicit open.
Definition: zbc.h:263

Test if a zone condition is explicit or implicit open.

#define zbc_zone_rwp_recommended (   z)
Value:
((z)->zbz_attributes & \
Definition: zbc.h:175

Test if a zone has the reset recommended flag set.

#define zbc_zone_sequential (   z)
Value:
#define zbc_zone_sequential_pref(z)
Test if a zone type is sequential write preferred.
Definition: zbc.h:247
#define zbc_zone_sequential_req(z)
Test if a zone type is sequential write required.
Definition: zbc.h:244

Test if a zone type is sequential write required or preferred.

Enumeration Type Documentation

SCSI Additional sense codes and qualifiers definitions.

SCSI Additional sense codes and additional sense code qualifiers inspected in case of command error.

Enumerator
ZBC_ASC_INVALID_FIELD_IN_CDB 

Invalid field in CDB

ZBC_ASC_LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE 

Logical block address out of range

ZBC_ASC_UNALIGNED_WRITE_COMMAND 

Unaligned write command

ZBC_ASC_WRITE_BOUNDARY_VIOLATION 

write boundary violation

ZBC_ASC_ATTEMPT_TO_READ_INVALID_DATA 

Attempt to read invalid data

ZBC_ASC_READ_BOUNDARY_VIOLATION 

Read boundary violation

ZBC_ASC_ZONE_IS_READ_ONLY 

Zone is in the read-only condition

ZBC_ASC_INSUFFICIENT_ZONE_RESOURCES 

Insufficient zone resources

ZBC_ASC_READ_ERROR 

Read error

ZBC_ASC_WRITE_ERROR 

Write error

ZBC_ASC_FORMAT_IN_PROGRESS 

Format in progress

Device flags definitions.

Defines device information flags.

Enumerator
ZBC_UNRESTRICTED_READ 

Indicates that a device has unrestricted read operation, i.e. that read commands spanning a zone write pointer or two consecutive zones of the same type will not result in an error.

Device model definitions.

Indicates the ZBC/ZAC device zone model, i.e host-aware, host-managed, device-managed or standard. Note that these last two models are not handled by libzbc (the device will be treated as a regular block device as it should).

  • Host-managed: device type 14h
  • Host-aware: device type 0h and zoned field equal to 01b
  • Device-managed: device type 0h and zoned field equal to 10b
  • Standard: device type 0h (standard block device)
Enumerator
ZBC_DM_DRIVE_UNKNOWN 

Unknown drive model.

ZBC_DM_HOST_AWARE 

Host-aware drive model: the device type/signature is 0x00 and the ZONED field of the block device characteristics VPD page B1h is 01b.

ZBC_DM_HOST_MANAGED 

Host-managed drive model: the device type/signature is 0x14/0xabcd.

ZBC_DM_DEVICE_MANAGED 

Drive-managed drive model: the device type/signature is 0x00 and the ZONED field of the block device characteristics VPD page B1h is 10b.

ZBC_DM_STANDARD 

Standard block device: the device type/signature is 0x00 and the ZONED field of the block device characteristics VPD page B1h is 00b.

Device type definitions.

Each type correspond to a different internal backend driver.

Enumerator
ZBC_DT_UNKNOWN 

Unknown drive type.

ZBC_DT_BLOCK 

Zoned block device (for kernels supporting ZBC/ZAC).

ZBC_DT_SCSI 

SCSI device.

ZBC_DT_ATA 

ATA device.

ZBC_DT_FAKE 

Fake device (emulation mode).

enum zbc_oflags

ZBC device open flags.

These flags can be combined together and passed to zbc_open to change that function default behavior. This is in particular useful for ATA devices to force using the ATA backend driver to bypass any SAT layer that may result in the SCSI backend driver being used.

Enumerator
ZBC_O_DRV_BLOCK 

Allow use of the block device backend driver

ZBC_O_DRV_SCSI 

Allow use of the SCSI backend driver

ZBC_O_DRV_ATA 

Allow use of the ATA backend driver

ZBC_O_DRV_FAKE 

Allow use of the fake device backend driver

Reporting options definitions.

Used to filter the zone information returned by the execution of a REPORT ZONES command. Filtering is based on the value of the reporting option and on the condition of the zones at the time of the execution of the REPORT ZONES command.

ZBC_RO_PARTIAL is not a filter: this reporting option can be combined (or'ed) with any other filter option to limit the number of reported zone information to the size of the REPORT ZONES command buffer.

Enumerator
ZBC_RO_ALL 

List all of the zones in the device.

ZBC_RO_EMPTY 

List the zones with a Zone Condition of ZBC_ZC_EMPTY.

ZBC_RO_IMP_OPEN 

List the zones with a Zone Condition of ZBC_ZC_IMP_OPEN.

ZBC_RO_EXP_OPEN 

List the zones with a Zone Condition of ZBC_ZC_EXP_OPEN.

ZBC_RO_CLOSED 

List the zones with a Zone Condition of ZBC_ZC_CLOSED.

ZBC_RO_FULL 

List the zones with a Zone Condition of ZBC_ZC_FULL.

ZBC_RO_RDONLY 

List the zones with a Zone Condition of ZBC_ZC_RDONLY.

ZBC_RO_OFFLINE 

List the zones with a Zone Condition of ZBC_ZC_OFFLINE.

ZBC_RO_RWP_RECOMMENDED 

List the zones with a zone attribute ZBC_ZA_RWP_RECOMMENDED set.

ZBC_RO_NON_SEQ 

List the zones with a zone attribute ZBC_ZA_NON_SEQ set.

ZBC_RO_NOT_WP 

List of the zones with a Zone Condition of ZBC_ZC_NOT_WP.

ZBC_RO_PARTIAL 

Partial report flag.

enum zbc_sk

SCSI Sense keys definitions.

SCSI sense keys inspected in case of command error.

Enumerator
ZBC_SK_NOT_READY 

Not ready

ZBC_SK_MEDIUM_ERROR 

Medium error

ZBC_SK_ILLEGAL_REQUEST 

Illegal request

ZBC_SK_DATA_PROTECT 

Data protect

ZBC_SK_ABORTED_COMMAND 

Aborted command

Zone attributes definitions.

Defines the attributes of a zone. Attributes validity depend on the zone type and device model.

Enumerator
ZBC_ZA_RWP_RECOMMENDED 

Reset write pointer recommended: a write pointer zone for which the device determined that a RESET WRITE POINTER command execution is recommended. The drive level condition resulting in this attribute being set depend on the drive model/vendor and not defined by the ZBC/ZAC specifications.

ZBC_ZA_NON_SEQ 

Non-Sequential Write Resources Active: indicates that a sequential write preferred zone (host-aware devices only) was written at a random LBA (not at the write pointer position). The drive may reset this attribute at any time after the random write operation completion.

Zone condition definitions.

A zone condition is determined by the zone type and the ZBC zone state machine, i.e. the operations performed on the zone.

Enumerator
ZBC_ZC_NOT_WP 

Not a write pointer zone (i.e. a conventional zone).

ZBC_ZC_EMPTY 

Empty sequential zone (zone not written too since last reset).

ZBC_ZC_IMP_OPEN 

Implicitely open zone (i.e. a write command was issued to the zone).

ZBC_ZC_EXP_OPEN 

Explicitly open zone (a write pointer zone was open using the OPEN ZONE command).

ZBC_ZC_CLOSED 

Closed zone (a write pointer zone that was written to and closed using the CLOSE ZONE command).

ZBC_ZC_RDONLY 

Read-only zone: any zone that can only be read.

ZBC_ZC_FULL 

Full zone (a write pointer zones only).

ZBC_ZC_OFFLINE 

Offline zone: unuseable zone.

Zone operation codes definitions.

Encode the operation to perform on a zone.

Enumerator
ZBC_OP_RESET_ZONE 

Reset zone write pointer.

ZBC_OP_OPEN_ZONE 

Open a zone.

ZBC_OP_CLOSE_ZONE 

Close a zone.

ZBC_OP_FINISH_ZONE 

Finish a zone.

Zone operation flag definitions.

Control the behavior of zone operations. Flags defined here can be or'ed together and passed to the functions zbc_open_zone, zbc_close_zone, zbc_finish_zone and link zbc_reset_zone.

Enumerator
ZBC_OP_ALL_ZONES 

Operate on all possible zones.

Zone type definitions.

Indicates the type of a zone.

Enumerator
ZBC_ZT_UNKNOWN 

Unknown zone type.

ZBC_ZT_CONVENTIONAL 

Conventional zone.

ZBC_ZT_SEQUENTIAL_REQ 

Sequential write required zone: a write pointer zone that must be written sequentially (host-managed drives only).

ZBC_ZT_SEQUENTIAL_PREF 

Sequential write preferred zone: a write pointer zone that can be written randomly (host-aware drives only).

Function Documentation

const char* zbc_asc_ascq_str ( enum zbc_asc_ascq  asc_ascq)

Returns a string describing a sense code.

Parameters
[in]asc_ascqSense code and sense code qualifier
Returns
A string describing a sense code and sense code qualifier.
int zbc_close ( struct zbc_device *  dev)

Close a ZBC device.

Parameters
[in]devDevice handle obtained with zbc_open

Performs the equivalent to close(2) for a ZBC device open using zbc_open.

Returns
Can return any error that close(2) may return.
int zbc_device_is_zoned ( const char *  filename,
bool  fake,
struct zbc_device_info info 
)

Test if a device is a zoned block device.

Parameters
[in]filenamePath to the device file
[in]fakeIf true, also test emulated devices
[in]infoAddress where to store the device information

Test if a device supports the ZBC/ZAC command set. If fake is false, only test physical devices. Otherwise, also test regular files and regular block devices that may be in use with the fake backend driver to create an emulated host-managed zoned block device. If info is not NULL and the device is identified as a zoned block device, the device information is returned at the address specified by info.

Returns
Returns a negative error code if the device test failed. 1 is returned if the device is identified as a zoned zoned block device. Otherwise, 0 is returned.
const char* zbc_device_model_str ( enum zbc_dev_model  model)

Returns a device zone model name.

Parameters
[in]modelDevice model
Returns
A string describing a device model.
const char* zbc_device_type_str ( enum zbc_dev_type  type)

Returns a device type name.

Parameters
[in]typeDevice type
Returns
A string describing the interface type of a device.
void zbc_errno ( struct zbc_device *  dev,
struct zbc_errno err 
)

Get detailed error code of last operation.

Parameters
[in]devDevice handle obtained with zbc_open
[out]errAddress where to return the error report

Returns at the address specified by err a detailed error report of the last command execued. The error report is composed of the SCSI sense key, sense code and sense code qualifier. For successsful commands, all three information are set to 0.

int zbc_flush ( struct zbc_device *  dev)

Flush a device write cache.

Parameters
[in]devDevice handle obtained with zbc_open

This an the equivalent to fsync/fdatasunc but operates at the device cache level.

Returns
Returns 0 on success and -EIO in case of error.
void zbc_get_device_info ( struct zbc_device *  dev,
struct zbc_device_info info 
)

Get a ZBC device information.

Parameters
[in]devDevice handle obtained with zbc_open
[in]infoAddress of the information structure to fill

Get information about an open device. The info parameter is used to return a device information. info must be allocated by the caller.

int zbc_list_zones ( struct zbc_device *  dev,
uint64_t  sector,
enum zbc_reporting_options  ro,
struct zbc_zone **  zones,
unsigned int *  nr_zones 
)

Get zone information.

Parameters
[in]devDevice handle obtained with zbc_open
[in]sectorSector from which to report zones
[in]roReporting options
[out]zonesThe array of zone information filled
[out]nr_zonesNumber of zones in the array zones

Similar to zbc_report_zones, but also allocates an appropriatly sized array of zone information structures and return the address of the array at the address specified by zones. The size of the array allocated and filled is returned at the address specified by nr_zones. Freeing of the memory used by the array of zone information strcutrues allocated by this function is the responsability of the caller.

Returns
Returns -EIO if an error happened when communicating with the device. Returns -ENOMEM if memory could not be allocated for zones.
int zbc_map_iov ( const void *  buf,
size_t  sectors,
struct iovec *  iov,
int  iovcnt,
size_t  iovlen 
)

Map a buffer to an I/O vector.

Parameters
[in]bufData buffer to map
[in]sectorsSize of buf in 512B sectors unit
[in]iovArray of I/O vectors to which buf will be mapped
[in]iovcntThe maximum number of entries in the iov array
[in]iovlenThe maximum size of a single I/O vector entry in 512B sectors.

Map the buffer buf to a set of I/O vectors of size iovlen. This is a utility function that is called by libzbc tools and test programs. It can be handy to library users as well.

Returns
the number of I/O vectors mapped or a negative error code in case of error
int zbc_open ( const char *  filename,
int  flags,
struct zbc_device **  dev 
)

Open a ZBC device.

Parameters
[in]filenamePath to a device file
[in]flagsDevice access mode flags
[out]devOpaque ZBC device handle

Opens the device pointed by filename, and returns a handle to it at the address specified by dev if the device is a zoned block device supporting the ZBC or ZAC command set. filename may specify the path to a regular block device file or a regular file to be used with libzbc emulation mode (ZBC_DT_FAKE device type). flags specifies the device access mode flags.O_RDONLY, O_WRONLY and O_RDWR can be specified. Other POSIX defined O_xxx flags are ignored. Additionally, if filename specifies the path to a zoned block device file or an emulated device, O_DIRECT can also be specified (this is mandatory to avoid unaligned write errors with zoned block device files). flags can also be or'ed with one or more of the ZBC_O_DRV_xxx flags in order to restrict the possible backend device drivers that libzbc will try when opening the device.

Returns
If the device is not a zoned block device, -ENXIO will be returned. Any other error code returned by open(2) can be returned as well.
ssize_t zbc_pread ( struct zbc_device *  dev,
void *  buf,
size_t  count,
uint64_t  offset 
)

Read sectors form a device.

Parameters
[in]devDevice handle obtained with zbc_open
[in]bufCaller supplied buffer to read into
[in]countNumber of 512B sectors to read
[in]offsetOffset where to start reading (512B sector unit)

This is the equivalent of the standard system call pread(2) that operates on a ZBC device handle and uses 512B sector unit addressing for the amount of data and the position on the device of the data to read. Attempting to read data across zone boundaries or after the write pointer position of a write pointer zone is possible only if the device allows unrestricted reads. This is indicated by the device information structure flags field, using the flag ZBC_UNRESTRICTED_READ. The range of 512B sectors to read, starting at offset and spanning count 512B sectors must be aligned on logical blocks boundaries. That is, for a 4K logical block size device, count and offset must be multiples of 8.

Returns
Any error returned by pread(2) can be returned. On success, the number of 512B sectors read is returned.
ssize_t zbc_preadv ( struct zbc_device *  dev,
const struct iovec *  iov,
int  iovcnt,
uint64_t  offset 
)

Read sectors from a device using mutliple buffers.

Parameters
[in]devDevice handle obtained with zbc_open
[in]iovCaller supplied read buffers to read into. Read buffer length is specified in 512B sectors
[in]iovcntNumber of iov buffers
[in]offsetOffset where to start reading (512B sector unit)

This is the equivalent of the standard system call preadv(2) and behaves otherwise as described in zbc_pread. The call reads iovcnt buffers from the file associated with zbc_open into the buffers described by iov ("scatter input").

void zbc_print_device_info ( struct zbc_device_info info,
FILE *  out 
)

Print a device information.

Parameters
[in]infoThe information to print
[in]outFile stream to print to

Print the content of info to the file stream out.

ssize_t zbc_pwrite ( struct zbc_device *  dev,
const void *  buf,
size_t  count,
uint64_t  offset 
)

Write sectors to a device.

Parameters
[in]devDevice handle obtained with zbc_open
[in]bufCaller supplied buffer to write from
[in]countNumber of 512B sectors to write
[in]offsetOffset where to start writing (512B sector unit)

This is the equivalent of the standard system call pwrite(2) that operates on a ZBC device handle, and uses 512B sector unit addressing for the amount of data and the position on the device of the data to write. On a host-aware device, any range of 512B sector is acceptable. On a host-managed device, the range os sectors to write can span several conventional zones but cannot span conventional and sequential write required zones. When writing to a sequential write required zone, offset must specify the current write pointer position of the zone. The range of 512B sectors to write, starting at offset and spanning count 512B sectors must be aligned on physical blocks boundaries. That is, for a 4K physical block size device, count and offset must be multiples of 8.

Returns
Any error returned by write(2) can be returned. On success, the number of logical blocks written is returned.
ssize_t zbc_pwritev ( struct zbc_device *  dev,
const struct iovec *  iov,
int  iovcnt,
uint64_t  offset 
)

Write sectors to a device unsig multiple buffers.

Parameters
[in]devDevice handle obtained with zbc_open
[in]iovCaller supplied write buffers to write from. Write buffer length is specified in 512B sectors
[in]iovcntNumber of iov buffers
[in]offsetOffset where to start writing (512B sector unit)

This is the equivalent of the standard system call pwritev(2) and behaves otherwise as described in zbc_pwrite. The call writes iovcnt buffers from the file associated with zbc_open from the buffers described by iov ("gather output").

int zbc_report_zones ( struct zbc_device *  dev,
uint64_t  sector,
enum zbc_reporting_options  ro,
struct zbc_zone zones,
unsigned int *  nr_zones 
)

Get zone information.

Parameters
[in]devDevice handle obtained with zbc_open
[in]sectorSector from which to report zones
[in]roReporting options
[in]zonesPointer to the array of zone information to fill
[out]nr_zonesNumber of zones in the array zones

Get zone information matching the sector and ro arguments and return the information obtained in the array zones and the number of zone information obtained at the address specified by nr_zones. The array zones must be allocated by the caller and nr_zones must point to the size of the allocated array (number of zone information structures in the array). The first zone reported will be the zone containing or after sector.

Returns
Returns -EIO if an error happened when communicating with the device.
void zbc_set_log_level ( char const *  log_level)

Set the library log level.

Parameters
[in]log_levelLibrary log level

Set the library log level using the level name specified by log_level. Log level are incremental: each level includes the levels preceding it. Valid log level names are: "none" : Silent operation (no messages) "warning" : Print device level standard compliance problems "error" : Print messages related to unexpected errors "info" : Print normal information messages "debug" : Verbose output decribing internally executed commands The default level is "warning".

const char* zbc_sk_str ( enum zbc_sk  sk)

Returns a string describing a sense key.

Parameters
[in]skSense key
Returns
A string describing a sense key.
const char* zbc_zone_condition_str ( enum zbc_zone_condition  cond)

Returns a string describing a zone condition.

Parameters
[in]condZone condition
Returns
A string describing a zone condition.
int zbc_zone_operation ( struct zbc_device *  dev,
uint64_t  sector,
enum zbc_zone_op  op,
unsigned int  flags 
)

Execute an operation on a zone.

Parameters
[in]devDevice handle obtained with zbc_open
[in]sectorFirst sector of the target zone
[in]opThe operation to perform
[in]flagsZone operation flags

Exexcute an operation on the zone of dev starting at the sector specified by sector. The target zone must be a write pointer zone, that is, its type must be ZBC_ZT_SEQUENTIAL_REQ or ZBC_ZT_SEQUENTIAL_PREF. The validity of the operation (reset, open, close or finish) depends on the condition of the target zone. See zbc_reset_zone, zbc_open_zone, zbc_close_zone and zbc_finish_zone for details. If ZBC_OP_ALL_ZONES is set in flags then sector is ignored and the operation is executed on all possible zones.

Returns
Returns -EIO if an error happened when communicating with the device.
const char* zbc_zone_type_str ( enum zbc_zone_type  type)

returns a string describing a zone type

Parameters
[in]typeZone type
Returns
A string describing a zone type.