[rtems-docs commit] POSIX Users: Add posix_devctl()

[Joel Sherrill]

Module:    rtems-docs
Branch:    master
Commit:    ca2926f595afde4c6ad1f87996a17c1556fa6e02
Changeset: http://git.rtems.org/rtems-docs/commit/?id=ca2926f595afde4c6ad1f87996a17c1556fa6e02

Author:    Joel Sherrill <joel at rtems.org>
Date:      Fri Mar 10 15:01:36 2017 -0600

POSIX Users: Add posix_devctl()

---

 posix-users/devctl.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++
 posix-users/index.rst  |  1 +
 2 files changed, 76 insertions(+)

diff --git a/posix-users/devctl.rst b/posix-users/devctl.rst
new file mode 100644
index 0000000..1282bdd
--- /dev/null
+++ b/posix-users/devctl.rst
@@ -0,0 +1,75 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT(c) 2017.
+.. COMMENT: On-Line Applications Research Corporation(OAR).
+.. COMMENT: All rights reserved.
+
+Device Control
+##############
+
+Introduction
+============
+
+The POSIX Device Control API is defined by POSIX 1003.26 and attempts
+to provides a portable alternative to the ioctl() service which is
+not standardized across POSIX implementations.  Support for this
+standard is required by the Open Group's FACE Technical Standard
+:cits:"FACE:2012:FTS".  Unfortunately, this part of the POSIX standard
+is not widely implemented.
+
+The services provided by the timer manager are:
+
+- posix_devctl_ - Control a Device
+
+Background
+==========
+
+Operations
+==========
+
+System Calls
+============
+
+This section details the POSIX device control's services.  A subsection
+is dedicated to each of this manager's services and describes the calling
+sequence, related constants, usage, and status codes.
+
+.. COMMENT: posix_devctl
+
+.. _posix_devctl
+
+posix_devctl - Control a Device
+-------------------------------
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+    #include <devctl.h>
+    int posix_devctl(
+      int            fd,
+      int            dcmd,
+      void *restrict dev_data_ptr,
+      size_t         nbyte,
+      int *restrict  dev_info_ptr
+    );
+
+**STATUS CODES:**
+
+The status codes returned reflect those returned by the ``ioctl()`` service
+and the underlying device drivers.
+
+**DESCRIPTION:**
+
+This method is intended to be a portable alternative to the ``ioctl()``
+method. The RTEMS implementation follows what is referred to as a library
+implementation which is a simple wrapper for the ``ioctl()`` method.
+The fd, fcmd, dev_data_ptr, and nbyte parameters are passed unmodified
+to the ``ioctl()`` method.
+
+If the dev_info_ptr parameter is not NULL, then the location pointed
+to by dev_info_ptr is set to 0.
+
+**NOTES:**
+
+NONE
diff --git a/posix-users/index.rst b/posix-users/index.rst
index b2e2154..9731702 100644
--- a/posix-users/index.rst
+++ b/posix-users/index.rst
@@ -60,6 +60,7 @@ to the Community Project hosted at http://www.rtems.org/.
 	thread_cancellation
 	services_provided_by_c
 	services_provided_by_math
+	devctl
 	status_of_implementation
 	command