sem_open_np()--Open Named Semaphore with Maximum Value

Syntax

 #include <semaphore.h>

 sem_t * sem_open_np(const char *name, int oflag, 
                     mode_t mode, unsigned int value,  
                     sem_attr_np_t * attr);

  Service Program Name: QP0ZPSEM

  Default Public Authority: *USE

  Threadsafe: Yes

The sem_open_np() function opens a named semaphore, returning a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close(). If a named semaphore is being created, the parameters mode, value, and attr are used to set the permissions, value, and maximum value of the created semaphore.

If sem_open_np() is called multiple times within the same process using the same name, sem_open_np() will return a pointer to the same semaphore, as long as another process has not used sem_unlink() to unlink the semaphore.

If sem_open_np() is called from a program using data model LLP64, the returned semaphore pointer must be declared as a sem_t *__ptr128.

Parameters

name

(Input) A pointer to the null-terminated name of the semaphore to be opened. The name should begin with a slash ('/') character. If the name does not begin with a slash ('/') character, the system adds a slash to the beginning of the name.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

The name is added to a set of names used by named semaphores only. The name has no relationship to any file system path names. The maximum length of the name is SEM_NAME_MAX.

See QlgSem_open_np()--Open Named Semaphore with Maximum Value (using NLS-enabled path name) for a description and an example of supplying the name in any CCSID.

oflag

(Input) Option flags.

The oflag parameter value is either zero or is obtained by performing an OR operation on one or more of the following constants:

'0x0008' or O_CREAT	Creates the named semaphore if it does not already exist.
'0x0010' or O_EXCL	Causes sem_open_np() to fail if O_CREAT is also set and the named semaphore already exists.

mode

(input) Permission flags.

The mode parameter value is either zero or is obtained by performing an OR operation on one or more of the list of constants. For another process to open the semaphore, the process's effective UID must be able to open the semaphore in both read and write mode.

'0x0100' or S_IRUSR	Permits the creator of the named semaphore to open the semaphore in read mode.
'0x0080' or S_IWUSR	Permits the creator of the named semaphore to open the semaphore in write mode.
'0x0020' or S_IRGRP	Permits the group associated with the named semaphore to open the semaphore in read mode.
'0x0010' or S_IWGRP	Permits the group associated with the named semaphore to open the semaphore in write mode.
'0x0004' or S_IROTH	Permits others to open the named semaphore in read mode.
'0x0002' or S_IWOTH	Permits others to open the named semaphore in write mode.

value

(Input) The initial value of the named semaphore.

attr

(Input) Attributes for the semaphore.

The members of the sem_attr_np_t structure are as follows:

unsigned int reserved1[1]	A reserved field that must be set to zero.
unsigned int maxvalue	The maximum value that the semaphore may obtain. maxvalue must be greater than zero. If a sem_post() or sem_post_np() operation would cause the value of a semaphore to exceed its maximum value, the operation will fail, returning EINVAL.
unsigned int reserved2[1]	A reserved field that must be set to zero.
char title[16]	The title of the semaphore. The title is a null-terminated string that has a maximum length of 16 bytes. The string is associated with the semaphore. If the first byte is zero, then the system assigns a title to the semaphore that is based on the semaphore name. The title is retrieved using the Open List of Interprocess Communication Objects (QP0ZOLIP) API.
void reserved3[2]*	A reserved field that must be set to zero.

Authorities

Authorization required for sem_open_np()

Object Referred to	Authority Required	errno
Named semaphore to be created	None	None
Existing named semaphore to be accessed	*RW	EACCES

Return Value

value	sem_open_np() was successful. The value returned is a pointer to the opened named semaphore.
SEM_FAILED	sem_open_np() was not successful. The errno variable is set to indicate the error.

Error Conditions

If sem_open_np() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

[EEXIST]

A named semaphore exists for the parameter name, but O_CREAT and O_EXCL are both set in oflag.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

The maxvalue field of the attr argument is greater than SEM_VALUE_MAX.

The maxvalue field of the attr argument is equal to zero.

The value argument is greater than the maxvalue field of the attr argument.

The reserved fields of the attr argument are not set to zero.

[ENAMETOOLONG]

The name is too long. The name is longer than the SEM_NAME_MAX characters.

[ENOENT]

No such path or directory.

The directory or a component of the path name specified does not exist.

A named file or directory does not exist or is an empty string.

The name specified on the sem_open_np() call does not refer to an existing named semaphore and O_CREAT was not set in oflag.

[ENOSPC]

No space available.

The requested operations required additional space on the device and there is no space left. This also could be caused by exceeding the user profile storage limit when creating or transferring ownership of an object.

Insufficient space remains to hold the intended file, directory, or link.

System semaphore resources have been exhausted.

Error Messages

None.

Related Information

The <semaphore.h> file (see Header Files for UNIX-Type Functions)
QlgSem_open_np()--Open Named Semaphore with Maximum Value (using NLS-enabled path name)
sem_close()--Close Named Semaphore
sem_getvalue()--Get Semaphore Value
sem_open()--Open Named Semaphore
sem_post()--Post to Semaphore
sem_post_np()--Post Value to Semaphore
sem_trywait()--Try to Decrement Semaphore
sem_unlink()--Unlink Named Semaphore
sem_wait()--Wait for Semaphore
sem_wait_np()--Wait for Semaphore with Timeout>

Example

See Code disclaimer information for information pertaining to code examples.

The following example opens the named semaphore "/mysemaphore" and creates the semaphore with an initial value of 10 and a maxiumum value of 11. The permissions are set such that only the current user has access to the semaphore.

#include <semaphore.h>
main() {
  sem_t * my_semaphore;
  int rc;
  sem_attr_np_t attr;

  memset(&attr, 0, sizeof(attr));
  attr.maxvalue=11;
  my_semaphore = sem_open_np("/mysemaphore",
                              O_CREAT|O_EXCL,
                              S_IRUSR | S_IWUSR,
                              10,
                              &attr);
}

API introduced: V4R4

Top | UNIX-Type APIs | APIs by category