.\" $MirOS: src/lib/libmbfun/cdblockedread.3,v 1.1 2010/08/14 21:10:19 tg Exp $
.\"-
.\" Copyright (c) 2010
.\"	Thorsten Glaser <tg@mirbsd.org>
.\"
.\" Provided that these terms and disclaimer and all copyright notices
.\" are retained or reproduced in an accompanying document, permission
.\" is granted to deal in this work without restriction, including un-
.\" limited rights to use, publicly perform, distribute, sell, modify,
.\" merge, give away, or sublicence.
.\"
.\" This work is provided "AS IS" and WITHOUT WARRANTY of any kind, to
.\" the utmost extent permitted by applicable law, neither express nor
.\" implied; without malicious intent or gross negligence. In no event
.\" may a licensor, author or contributor be held liable for indirect,
.\" direct, other damage, loss, or other issues arising in any way out
.\" of dealing in the work, even if advised of the possibility of such
.\" damage or existence of a defect, except proven that it results out
.\" of said person's immediate fault when using the work as intended.
.\"-
.Dd $Mdocdate: August 14 2010 $
.Dt CDBLOCKEDREAD 3
.Os
.Sh NAME
.Nm cdblockedread
.Nd seek and read with 2048-byte alignment
.Sh SYNOPSIS
.In mbfun.h
.Ft ssize_t
.Fn cdblockedread "int fd" "void *dst" "size_t len" "off_t ofs"
.Sh DESCRIPTION
The
.Fn cdblockedread
function equals the following calls:
.Bd -literal -offset indent
lseek(fd, ofs, SEEK_SET);
read(fd, dst, len);
.Ed
.Pp
It however differs from that sequence in that it does proper error
checking and I/O aligned to 2048 bytes, that is
.Fa ofs
is truncated down to a multiple of 2048, the difference is added to
.Fa len
which then is rounded up to a multiple of 2048, a temporary buffer
is allocated to which the bytes are read, the correct bytes are
then copied to
.Fa dst
and another
.Xr lseek 2
to the original
.Fa ofs + len
is done to set the file seek pointer to the same value the above
sequence of calls would have.
.Pp
This function is of limited use cases; one would be to read a random
512-byte sector from a CD-ROM using the raw mode (character) device;
.Xr disklabel 8
does that.
.Sh RETURN VALUES
If no error occured and the call to
.Xr read 2
returned exactly
.Fa len
bytes in one operation,
.Fn cdblockedread
returns
.Fa len .
Otherwise, if the last call to
.Xr lseek 2
failed but everything else succeeded, 0 is returned, \-1 otherwise.
This is because the seek pointer after reading is irrelevant to
most applications using it.
.Sh SEE ALSO
.Xr lseek 2 ,
.Xr read 2 ,
.Xr cd 4
.Sh HISTORY
The
.Nm cdblockedread
function is an
.Mx BSD
extension and first appeared in
.Mx 11 .
.Sh AUTHORS
.An Thorsten Glaser Aq tg@mirbsd.org