Module Name: src Committed By: kamil Date: Sat Sep 9 18:00:40 UTC 2017
Modified Files: src/lib/libc/gen: devname.3 Log Message: Document devname_r(3) in devname(3). Improve clarity of devname(3) mentioning that it returns a pointer to the buffer pointer. This approach is not thread-safe and not reentrant. Not that devname(3) does not set errno on failure and document it as a bug. To generate a diff of this commit: cvs rdiff -u -r1.12 -r1.13 src/lib/libc/gen/devname.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/lib/libc/gen/devname.3 diff -u src/lib/libc/gen/devname.3:1.12 src/lib/libc/gen/devname.3:1.13 --- src/lib/libc/gen/devname.3:1.12 Sun Jun 3 21:42:46 2012 +++ src/lib/libc/gen/devname.3 Sat Sep 9 18:00:39 2017 @@ -1,4 +1,4 @@ -.\" $NetBSD: devname.3,v 1.12 2012/06/03 21:42:46 joerg Exp $ +.\" $NetBSD: devname.3,v 1.13 2017/09/09 18:00:39 kamil Exp $ .\" .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. @@ -29,11 +29,12 @@ .\" .\" @(#)devname.3 8.2 (Berkeley) 4/29/95 .\" -.Dd June 3, 2012 +.Dd September 9, 2017 .Dt DEVNAME 3 .Os .Sh NAME -.Nm devname +.Nm devname , +.Nm devname_r .Nd get device name .Sh LIBRARY .Lb libc @@ -42,10 +43,12 @@ .In sys/stat.h .Ft char * .Fn devname "dev_t dev" "mode_t type" +.Ft int +.Fn devname_r "dev_t dev" "mode_t type" "char *path" "size_t len" .Sh DESCRIPTION The .Fn devname -function returns a pointer to the name of the block or character +function returns a pointer to the static buffer with the name of the block or character device in .Dq Pa /dev with a device number of @@ -58,9 +61,49 @@ available, .Dv NULL is returned. .Pp +The +.Fn devname_r +function is a reentrand and thread-safe version of +.Fn devname . +This function returns the device name by copying it into the +.Fa path +argument with up to +.Fa len +characters. +The +.Fa path +argument is always nul-terminated. +.Pp The traditional display for applications when no device is found is the string .Dq ?? . +.Sh RETURN VALUES +If successful, +.Fn devname +returns a pointer to a nul-terminated string containing the name of the device. +If an error occurs +.Fa devname +will return +.Dv NULL . +.Pp +If successful, +.Fn devname_r +places a nul-terminated string containing the name of the device and returns 0. +If error occurs +.Fn devname_r +will return error number indicating what went wrong. +.Sh ERRORS +The +.Fn devname +and +.Fn devname_r +functions my fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +the corresponding device does not exist +.It Bq Er ERANGE +the passed buffer length is too short +.El .Sh FILES .Bl -tag -width /var/run/dev.cdb -compact .It Pa /var/run/dev.cdb @@ -74,3 +117,12 @@ The .Nm devname function call appeared in .Bx 4.4 . +.Pp +The +.Fn devname_r +function first appeared in +.Nx 6.0 . +.Sh BUGS +The +.Fn devname +function does not set errno on failure.