1.\" $MirOS: src/lib/libmbfun/cdblockedread.3,v 1.1 2010/08/14 21:10:19 tg Exp $ 2.\"- 3.\" Copyright (c) 2010 4.\" Thorsten Glaser <tg@mirbsd.org> 5.\" 6.\" Provided that these terms and disclaimer and all copyright notices 7.\" are retained or reproduced in an accompanying document, permission 8.\" is granted to deal in this work without restriction, including un- 9.\" limited rights to use, publicly perform, distribute, sell, modify, 10.\" merge, give away, or sublicence. 11.\" 12.\" This work is provided "AS IS" and WITHOUT WARRANTY of any kind, to 13.\" the utmost extent permitted by applicable law, neither express nor 14.\" implied; without malicious intent or gross negligence. In no event 15.\" may a licensor, author or contributor be held liable for indirect, 16.\" direct, other damage, loss, or other issues arising in any way out 17.\" of dealing in the work, even if advised of the possibility of such 18.\" damage or existence of a defect, except proven that it results out 19.\" of said person's immediate fault when using the work as intended. 20.\"- 21.Dd $Mdocdate: August 14 2010 $ 22.Dt CDBLOCKEDREAD 3 23.Os 24.Sh NAME 25.Nm cdblockedread 26.Nd seek and read with 2048-byte alignment 27.Sh SYNOPSIS 28.In mbfun.h 29.Ft ssize_t 30.Fn cdblockedread "int fd" "void *dst" "size_t len" "off_t ofs" 31.Sh DESCRIPTION 32The 33.Fn cdblockedread 34function equals the following calls: 35.Bd -literal -offset indent 36lseek(fd, ofs, SEEK_SET); 37read(fd, dst, len); 38.Ed 39.Pp 40It however differs from that sequence in that it does proper error 41checking and I/O aligned to 2048 bytes, that is 42.Fa ofs 43is truncated down to a multiple of 2048, the difference is added to 44.Fa len 45which then is rounded up to a multiple of 2048, a temporary buffer 46is allocated to which the bytes are read, the correct bytes are 47then copied to 48.Fa dst 49and another 50.Xr lseek 2 51to the original 52.Fa ofs + len 53is done to set the file seek pointer to the same value the above 54sequence of calls would have. 55.Pp 56This function is of limited use cases; one would be to read a random 57512-byte sector from a CD-ROM using the raw mode (character) device; 58.Xr disklabel 8 59does that. 60.Sh RETURN VALUES 61If no error occured and the call to 62.Xr read 2 63returned exactly 64.Fa len 65bytes in one operation, 66.Fn cdblockedread 67returns 68.Fa len . 69Otherwise, if the last call to 70.Xr lseek 2 71failed but everything else succeeded, 0 is returned, \-1 otherwise. 72This is because the seek pointer after reading is irrelevant to 73most applications using it. 74.Sh SEE ALSO 75.Xr lseek 2 , 76.Xr read 2 , 77.Xr cd 4 78.Sh HISTORY 79The 80.Nm cdblockedread 81function is an 82.Mx BSD 83extension and first appeared in 84.Mx 11 . 85.Sh AUTHORS 86.An Thorsten Glaser Aq tg@mirbsd.org 87