From keld@dkuug.dk Tue May 11 19:03:40 1993
Received: by dkuug.dk id AA05246
  (5.65c8/IDA-1.4.4j for sc22wg15); Tue, 11 May 1993 17:03:41 +0200
Message-Id: <199305111503.AA05246@dkuug.dk>
From: keld@dkuug.dk (Keld J|rn Simonsen)
Date: Tue, 11 May 1993 17:03:40 +0200
X-Charset: ASCII
X-Char-Esc: 29
Mime-Version: 1.0
Content-Type: Text/Plain; Charset=ISO-8859-1
Content-Transfer-Encoding: 8bit
Mnemonic-Intro: 29
X-Mailer: Mail User's Shell (7.2.2 4/12/91)
To: sc22wg15@dkuug.dk
Subject: Example thin C LIS binding

.so /usr/lib/tmac/tmac.e
.sp 3
Title: Thin C binding

Source: Keld Simonsen

Status: Expert contribution

Date: 1993-05-11

Action: for WG15 to consider at May 1993 meeting
.ce 20
.ft B
.sp 5
.ps 18
.vs 20
POSIX C

Programming Language C

binding for ISO/IEC 9945-1

.ps
.vs
Discussion paper
.ft
.ce 0
.bp
.2c
Foreword

This is a "thin" binding for the programming language C to
the POSIX Application Programming Interface (API) standard
ISO/IEC 9945-1. It is intended as just giving the syntax for the C API,
with the semantics defined in the Language Independent Specification
(LIS) of the standard. As well as being the formal binding
specification for C, it is intended to be used as a reference card.

This document is intended as a discussion paper to see how 
this strategy could be worked out. All teh functions in POSIX.16/D2
have been included. I have not yet had a look
on how to incorporate header files, but my idea is to just include
them as they are. Sequences of ?? implies someeting unfinished.

Keld Simonsen
1993-05-11
.bp
.sh 1 "Introduction"

(to be supplied).

.sh 1 Scope

(to be supplied).

.sh 1 "Normative references"

The follwing standards contain provisions which, through references in this
text, constitute provisions of this standard. At the time of publication
the editions indicated were valid. All standards are subject to revision,
and parties to agreements based on this International
Standard are encouraged to investigate the possibility of 
appying the most recent editions of the standards listed
below. Members of IEC and ISO maintain registers of currently valid
International Standards.

(1)
ISO/IEC 646:1992 Information Processing - ISO 7-bit coded character
set for information interchange.

(2)
ISO/IEC 9899:1990 Programming Languages - C

(3)
ISO/IEC 9945-1:199x Information technology - Portable Operating
System Interface (POSIX) - Part 1: System Application Programming
Interface (API) (Language Independent)

.sh 1 "Binding Technique"

This "thin" language binding of the C programming language to
the POSIX API uses a short notation, to make the binding short, concise
and widely usable for reference purposes by language implementors
as well as programmers.

The binding technique used is:

A function name is bound to the POSIX API via the section
number in the POSIX API (3), and the parameters are then bound
to the parameters in (3) in the sequence specified in (3).

Header files which are needed are listed above the functions
without any intervening blank lines and apply to the functions
below until a blank line.

In this way the document can be used as a short reference
as well as a normative binding specification, and readers
need not deal with the specific syntax and nomenclature of
the POSIX API (3).

.sh 1 "error values"

(filled in later)

.sh 1 "Functions"

.sh 2 "process handling"

.nf
3.1.1 pid_t fork(void);
3.1.2.1 int execl(const char *path, const char *arg, ...);
3.1.2.2 int execv(const char *path, char *const argv[]);
3.1.2.3 int execle(const char *path, const char *arg, ...);
3.1.2.4 int execve(const char *path, char *const argv[], char *const envp[])
3.1.2.5 int execlp(const char *file, const char *arg, ...);
3.1.2.6 int execvp(const char *file, char *const argv[]);

#include <sys/types.h>
#include <sys/wait.h>
3.2.1 pid_t wait(int *stat_loc);
3.2.1 pid_t waitpid(pid_t pid, int *stat_loc, int options);

3.2.2 void _exit(int status);
3.2.3 void abort(int status);

.sh 2 "Signals"

?? constants etc

#include <sys/types.h>
#include <sys/signal.h>
3.3.2 int kill(pid_t pid, int sig);

#include <signal.h>
3.3.3.1 int sigemptyset(sigset_t *set);  ??
3.3.3.2 int sigfillset(sigset_t *set);  ??
3.3.3.3 int sigaddset(sigset_t *set, int signo);  ??
3.3.3.4 int sigdelset(sigset_t *set, int signo);  ??
3.3.3.5 int sigismember(const sigset_t *set, int signo);  ??
3.3.4 int sigaction(int sig, const struct sicaction *act,
    struct sigaction *oact); ??
3.3.5 int sigprocmask(int how, const sigset_t *set,
      sigset_t *oset); ??
3.3.6 int sigpending(sigset_t *set);
3.3.7 int sigsuspend(const sigset_t *sigmask);

.fi
.sh 2 "Timer Operations"
.nf
3.4.1 unsigned int alarm(unsigned int seconds);
3.4.2 int pause(void);
3.4.3 unsigned int sleep(unsigned int seconds);

.fi
.sh 1 "Process Environment"

.sh 2 "Process Identification"
.nf

#include <sys/types.h>
4.1.1 pid_t getpid(void);
4.1.2 pid_t getppid(void);
4.2.1.1 uid_t getuid(void);
4.2.1.2 uid_t geteuid(void);
4.2.1.3 gid_t getgid(void);
4.2.1.4 gid_t getegid(void);
4.2.2.1 int setuid(uid_t uid);
4.2.2.2 int setgid(gid_t gid);
4.2.3 int getgroups(int gidsettime, gid_t grouplist[]);

4.2.4 char *getlogin(void);

#include <sys/types.h>
4.3.1 pid_t getpgrp(void);
4.3.2 pid_t setsid(void);
4.3.3 pid_t setpgid(void);

.fi
.sh 2 "System Identification"
.nf

#include <sys/utsname.h>
int uname(struct utsname *name);

.fi
.sh 2 "Time"
.nf

#include <time.h>
4.5.1 time_t time(time_t *tloc);

#include <sys/times.h>
4.5.2 clock_t times(struct tms *buffer);

#include <stdlib.h>
4.6.1 char *getenv(const char *name);

4.6.2 extern char **environ;

#include <stdio.h>
4.7.1 char *ctermid(char *s);

4.7.2.1 char *ttyname(int fildes);
4.7.2.2 int isatty(int fildes);

#include  <unistd.h>
4.8.1 long sysconf(int name);

.fi
.sh 2 "Files and Directories"
.nf

struct dirent {
char *d_name;

#include <sys/types.h>
#include <dirent.h>
5.1.2.1 DIR *opendir(const char *dirname);
5.1.2.2 struct dirent *readdir(DIR *dirp);
5.1.2.3 void rewinddir(DIR *dirp);
5.1.2.4 int closedir(DIR *dirp);

5.2.1    int chdir(const char *path);
5.2.2    char *getcwd(char *buf, size_t size);

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
5.3.1 int open(const char *path, int oflag, ...);
5.3.2 int creat(const char *path, mode_t mode);

#include <sys/types.h>
#include <sys/stat.h>
5.3.3 mode_t umask(mode_t cmask);

5.3.4 int link(const char *existing, const char *new);

#include <sys/types.h>
#include <sys/stat.h>
5.4.1 int mkdir(const char *path, mode_t mode);
5.4.2 int mkfifo(const char *path, mode_t mode);

5.5.1 int unlink(const char *path);
5.5.2 int rmdir(const char *path);
5.5.3 int rename(const char *old, const char *new);

<sys/stat.h> 
struct stat;
<sys/types.h>
????

#include <sys/types.h>
#include <sys/stat.h>
5.6.2.1 int stat(const char *path, struct stat *buf);
5.6.2.2 int fstat(int fildes, struct stat *buf);

#include <unistd.h>
5.6.3 int access(const char *path, int amode);

#include <sys/types.h>
#include <sys/stat.h>
5.6.4 int chmod(const char *path, mode_t mode);

#include <sys/types.h>
5.6.5 int chown(const char *path, uid_t owner, gid_t group);

#include <sys/types.h>
#include <utime.h>
5.6.5 int utime(const char *path, const struct utimbuf *times);

struct utimbuf ??

#include <unistd.h>
5.7.1.1 long pathconf(const char *path, int name);
5.7.1.2 long fpathconf(int fildes, int name);  ??

.fi
.sh 2 "Input and Output Primitives"
.nf

6.1.1 int pipe(int fildes[2]);
6.2.1.1 int dup(int fildes);
6.2.1.2 int dup2(int fildes, int fildes2);
6.3.1 int close(int fildes);
6.4.1 ssize_t read(int fildes, void *buf, size_t nbyte);
6.4.2 ssize_t write(int fildes, const void *buf, size_t nbyte);

6.5.1 ??

#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>
6.5.2 int fcntl(int fildes, int cmd, ...); ??

#include <sys/types.h>
#include <unistd.h>
6.5.3 off_t lseek(int fildes, off_t offset, int whence);

6.6.1 ?? <fcntl.h>

#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>
6.6.2 int fcntl(int fildes, int cmd, struct flock arg); ??
6.6.3 int fcntl(int fildes, int cmd, struct flock arg); ??

.fi
.sh 2 "Terminal Handling"
.nf

7.1.2 termios ??

#include <termios.h>
7.1.3.1 speed_t cfgetospeed(const struct termios *termios_p);
7.1.3.2 int cfsetospeed(const struct termios *termios_p, speed_t speed);
7.1.3.3 speed_t cfgetispeed(const struct termios *termios_p);
7.1.3.4 int cfsetispeed(const struct termios *termios_p, speed_t speed);
7.2.1.1 int tcgetattr(int fildes, const struct termios *termios_p);
7.2.1.2 int tcsetattr(int fildes, int optional_actions, const struct termios *termios_p); ??
7.2.2.1 int tcsendbreak(int fildes, int duration);
7.2.2.2 int tcdrain(int fildes);
7.2.2.3 int tcflush(int fildes, int queue_selector); ??
7.2.2.4 int tcflow(int fildes, int action); ??

#include <sys/types.h>
7.2.3 pid_t tcgetpgrp(int fildes);
7.2.4 int tcsetpgrp(int fildes, pid_t pgrp_id);

.fi
.sh 2 "Language Specific C routines"
.nf

8.1.1 exit(), abort() ??
8.1.2 TZ ??
8.1.3 ??

#include <setjmp.h>
8.2.1.1 int sigsetjmp(sigjmp_buf env, int savemask);
8.2.1.2 void siglongjmp(sigjmp_buf env, int val);

#include <time.h>
8.2.2 void tzset(void);

#include <stdio.h>
8.2.3 int fileno(FILE *stream);
8.2.4 FILE *fdopen(int fildes, const char *type);

#include <sys/types.h>
#include <grp.h>
9.1.1 struct group *getgrgid(gid_t gid);
9.1.2 struct group *getgrname(const char *name);

#include <sys/types.h>
#include <pwd.h>
9.2.1 struct passwd *getpwuid(uid_t uid);
9.2.2 struct passwd *getpwname(const char *name);

.fi
.sh 1 "Header files"

(to be filled in).