From f36575b51cb531d9674869c8a4039526d1c384f2 Mon Sep 17 00:00:00 2001
From: Jaakko Heinonen <jh@FreeBSD.org>
Date: Sun, 24 Oct 2010 15:56:21 +0000
Subject: [PATCH] Document make_dev_p(9).

Reviewed by:	brueffer, kib
---
 share/man/man9/Makefile   |  3 +-
 share/man/man9/make_dev.9 | 63 ++++++++++++++++++++++++++++++++++++---
 2 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 79ba70b83b34..e6a490a9d98a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -775,7 +775,8 @@ MLINKS+=make_dev.9 destroy_dev.9 \
 	make_dev.9 dev_depends.9 \
 	make_dev.9 make_dev_alias.9 \
 	make_dev.9 make_dev_cred.9 \
-	make_dev.9 make_dev_credf.9
+	make_dev.9 make_dev_credf.9 \
+	make_dev.9 make_dev_p.9
 MLINKS+=malloc.9 free.9 \
 	malloc.9 MALLOC_DECLARE.9 \
 	malloc.9 MALLOC_DEFINE.9 \
diff --git a/share/man/man9/make_dev.9 b/share/man/man9/make_dev.9
index 2e35f5fc81bc..d846d57a1419 100644
--- a/share/man/man9/make_dev.9
+++ b/share/man/man9/make_dev.9
@@ -24,13 +24,14 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 7, 2010
+.Dd October 24, 2010
 .Dt MAKE_DEV 9
 .Os
 .Sh NAME
 .Nm make_dev ,
 .Nm make_dev_cred ,
 .Nm make_dev_credf ,
+.Nm make_dev_p ,
 .Nm make_dev_alias ,
 .Nm destroy_dev ,
 .Nm destroy_dev_sched ,
@@ -49,6 +50,8 @@ and DEVFS registration for devices
 .Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ...
 .Ft struct cdev *
 .Fn make_dev_credf "int flags" "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ...
+.Ft int
+.Fn make_dev_p "int flags" "struct cdev **cdev" "struct cdevsw *devsw" "struct ucred *cr" "uid_t uid" "gid_t gid" "int mode" "const char *fmt" ...
 .Ft struct cdev *
 .Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ...
 .Ft void
@@ -128,20 +131,22 @@ member of the initialized
 The
 .Va flags
 argument alters the operation of
-.Fn make_dev_credf .
+.Fn make_dev_credf
+or
+.Fn make_dev_p .
 The following values are currently accepted:
 .Pp
 .Bl -tag -width "MAKEDEV_CHECKNAME" -compact -offset indent
 .It MAKEDEV_REF
 reference the created device
 .It MAKEDEV_NOWAIT
-do not sleep, may return NULL
+do not sleep, the call may fail
 .It MAKEDEV_WAITOK
 allow the function to sleep to satisfy malloc
 .It MAKEDEV_ETERNAL
 created device will be never destroyed
 .It MAKEDEV_CHECKNAME
-return NULL if the device name is invalid or already exists
+return an error if the device name is invalid or already exists
 .El
 .Pp
 The
@@ -190,6 +195,14 @@ make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...);
 .Ed
 .Pp
 The
+.Fn make_dev_p
+function is similar to
+.Fn make_dev_credf
+but it may return an error number and takes a pointer to the resulting
+.Ft *cdev
+as an argument.
+.Pp
+The
 .Fn make_dev_alias
 function takes the returned
 .Ft cdev
@@ -293,6 +306,44 @@ is called for all instantiated devices, but need to postpone module
 unload until
 .Fn destroy_dev
 is actually finished for all of them.
+.Sh RETURN VALUES
+If successful,
+.Fn make_dev_p
+will return 0, otherwise it will return an error.
+If successful,
+.Fn make_dev_credf
+will return a valid
+.Fa cdev
+pointer, otherwise it will return
+.Dv NULL .
+.Sh ERRORS
+The
+.Fn make_dev_p
+call will fail and the device will be not registered if:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+The
+.Dv MAKEDEV_NOWAIT
+flags was specified and a memory allocation request could not be satisfied.
+.It Bq Er ENAMETOOLONG
+The
+.Dv MAKEDEV_CHECKNAME
+flags was specified and the provided device name is longer than
+.Dv SPECNAMELEN .
+.It Bq Er EINVAL
+The
+.Dv MAKEDEV_CHECKNAME
+flags was specified and the provided device name is empty, contains a
+.Qq \&.
+or
+.Qq ..
+path component or ends with
+.Ql / .
+.It Bq Er EEXIST
+The
+.Dv MAKEDEV_CHECKNAME
+flags was specified and the provided device name already exists.
+.El
 .Pp
 .Sh SEE ALSO
 .Xr devctl 4 ,
@@ -320,3 +371,7 @@ The functions
 .Fn destroy_dev_sched_cb
 first appeared in
 .Fx 7.0 .
+The function
+.Fn make_dev_p
+first appeared in
+.Fx 8.2 .