Add POSIX Method Signature Compliance Tests

Directions for Students

Prerequisite: You must have completed the "Getting Started: Hello World" task or equivalently done the GSoC Getting Started Guide before attempting this task.

Creating a Test

First, verify this is header file available in the RTEMS environment. If not, please contact your mentors.

To create a test, you'll need to be in the rtems/testsuite/psxtests/psxheader/@your_header@ directory. Note that the @your_header@ directory will be the name of the header file without the .h. For example, stdio.h related tests will be in psxtests/psxhdr/stdio and those for sys/mman.h are in sys/mman.

For the header file you have been given, you will be creating a simple test case that verifies that RTEMS matches the POSIX defined signature of the method as defined at ​http://pubs.opengroup.org/onlinepubs/9699919799/. Search for the header file you have been assigned and check every method that is in it. For each method, its specification page will have something like this (from time()):

The test for time() is in psxtests/psxhdr/time/time.c and (ignoring comments and boilerplate) is as follows:

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <time.h>

int test( void );

int test( void )
{
  time_t    new_time;

  new_time = time( &new_time );

  return (new_time != -1);
}

Note that a variable of each time passed in and returned is declared. The POSIX standard told us that time() could be invoked by including only the <time.h> header file and this test verifies that RTEMS follows the standard.

Each header file has multiple methods. Each goes in a separate file.

Use other existing tests as guides but note that some do not follow the proper Doxygen style expected now in RTEMS. Please use current style like pthread/pthread_getconcurrency.c:

/**
 *  @file
 *  @brief pthread_getconcurrency() API Conformance Test
 */

Use the 2-Clause BSD License found at ​https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause:

/*
 * SPDX-License-Identifier: BSD-2-Clause
 * 
 * Copyright (C) <YEAR> <COPYRIGHT HOLDER>
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

You are the copyright holder. Copy the comment above to the top of the file. Replace the <YEAR> placeholder with the GCI year. Replace the <COPYRIGHT HOLDER> placeholder with your name. You must not alter anything else in the license comment.

Adding the Test to the Build System

To add a test to the build system, you'll need to add it to psxtests/Makefile.am. Search for psxhdrs in the Makefile.am and then just add your new files to the list.

Then you'll need to "bootstrap" from the psxtests directory.

Now bootstrap it

 cd ~/rtems/testsuites/psxtests
 ~/rtems> ../../bootstrap

Now build...

 cd ../b-erc32
 ../rtems/configure --options --used --to --configure

Be sure to include --enable-tests on the configure command.

These tests are compile only and are not intended to be executed.

Directions for Mentors

This should be evaluated as a normal code submission. You need to review and verify the tests compile warning free to ensure it is correct. These are compile-only tests. It should be based on the templates in rtems-testing. The student should provide a name and email for proper attribution. If you have write permission, commit it. Otherwise, send it to devel@… for another developer to commit with commentary indicating it is acceptable and from GCI.

Ensure the license and Doxygen file headers are correct.

Ensure it is using the 2-Clause BSD License.