pthread.pod

Linux下的中文输入法

=item [EINVAL]

The value of
I<stacksize>
is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit.

=back

These functions will not return an error code of [EINTR].

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_attr_init()>,
I<pthread_attr_setstackaddr()>,
I<pthread_attr_setdetachstate()>,
I<pthread_create()>,
I<<limits.h>>,
I<<pthread.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_attr_init,> B<pthread_attr_destroy>
- initialise and destroy threads attribute object

=head1 SYNOPSIS

#include <pthread.h>

int pthread_attr_init(pthread_attr_t *I<attr>);
int pthread_attr_destroy(pthread_attr_t *I<attr>);

=head1 DESCRIPTION

The function
I<pthread_attr_init()>
initialises a thread attributes object
I<attr>
with the default value for all of the individual attributes
used by a given implementation.

The resulting attribute object
(possibly modified by setting individual attribute values),
when used by
I<pthread_create()>,
defines the attributes of the thread created.
A single attributes object can be used in multiple simultaneous calls to
I<pthread_create()>.

The
I<pthread_attr_destroy()>
function is used to destroy a thread attributes object.
An implementation may cause
I<pthread_attr_destroy()>
to set
I<attr>
to an implementation-dependent invalid value.
The behaviour of using the attribute after it has been destroyed is undefined.

=head1 RETURN VALUE

Upon successful completion,
I<pthread_attr_init()>
and
I<pthread_attr_destroy()>
return a value of 0.
Otherwise, an error number is returned to indicate the error.

=head1 ERRORS

The
I<pthread_attr_init()>
function will fail if:

=over 4

=item [ENOMEM]

Insufficient memory exists to initialise the thread attributes object.

=back

These functions will not return an error code of [EINTR].

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_attr_setstackaddr()>,
I<pthread_attr_setstacksize()>,
I<pthread_attr_setdetachstate()>,
I<pthread_create()>,
I<<pthread.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_attr_setdetachstate,> B<pthread_attr_getdetachstate>
- set and get detachstate attribute

=head1 SYNOPSIS

#include <pthread.h>

int pthread_attr_setdetachstate(pthread_attr_t *I<attr>, int I<detachstate>);
int pthread_attr_getdetachstate(const pthread_attr_t *I<attr>,
int *I<detachstate>);

=head1 DESCRIPTION

The
I<detachstate>
attribute controls whether the thread is created in a detached state.
If the thread is created detached,
then use of the ID of the newly created thread by the
I<pthread_detach()>
or
I<pthread_join()>
function is an error.

The
I<pthread_attr_setdetachstate()>
and
I<pthread_attr_getdetachstate()>,
respectively, set and get the
I<detachstate>
attribute in the
I<attr>
object.

The
I<detachstate>
can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.
A value of PTHREAD_CREATE_DETACHED causes all threads created with
I<attr>
to be in the detached state, whereas using a value of
PTHREAD_CREATE_JOINABLE
causes all threads created with
I<attr>
to be in the joinable state.
The default value of the
I<detachstate>
attribute is
PTHREAD_CREATE_JOINABLE .

=head1 RETURN VALUE

Upon successful completion,
I<pthread_attr_setdetachstate()>
and
I<pthread_attr_getdetachstate()>
return a value of 0.
Otherwise, an error number is returned to indicate the error.

The
I<pthread_attr_getdetachstate()>
function stores the value of the
I<detachstate>
attribute in
I<detachstate>
if successful.

=head1 ERRORS

The
I<pthread_attr_setdetachstate()>
function will fail if:

=over 4

=item [EINVAL]

The value of
I<detachstate>
was not valid

=back

These functions will not return an error code of [EINTR].

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_attr_init()>,
I<pthread_attr_setstackaddr()>,
I<pthread_attr_setstacksize()>,
I<pthread_create()>,
I<<pthread.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_attr_getguardsize,> B<pthread_attr_setguardsize> -
get or set the thread guardsize attribute

=head1 SYNOPSIS

#include <pthread.h>

int pthread_attr_getguardsize(const pthread_attr_t I<*attr>,
size_t I<*guardsize>);
int pthread_attr_setguardsize(pthread_attr_t I<*attr>,
size_t I<guardsize>);

=head1 DESCRIPTION

The I<guardsize> attribute controls the size
of the guard area for the created thread's stack. The I<guardsize>
attribute provides protection against overflow of the
stack pointer. If a thread's stack is created with guard
protection, the implementation allocates extra
memory at the overflow end of the stack as a buffer against
stack overflow of the stack pointer. If an application
overflows into this buffer an error results (possibly
in a SIGSEGV signal being delivered to the thread).

The I<guardsize> attribute is provided to the application
for two reasons:

=over 4

=item 1.

Overflow protection can potentially
result in wasted system resources. An application that creates a large
number of threads, and which knows its threads will never overflow
their stack, can save system resources by turning off guard areas.

=item 2.

When threads allocate large data structures on the stack,
large guard areas may be needed to detect stack overflow.

=back

The
I<pthread_attr_getguardsize()>
function gets the
I<guardsize> attribute in the I<attr> object. This attribute is
returned in the I<guardsize> parameter.

The
I<pthread_attr_setguardsize()>
function sets the
I<guardsize> attribute in the I<attr> object. The new value of
this attribute is obtained from the I<guardsize> parameter.
If I<guardsize> is zero, a guard area will not be
provided for threads created with I<attr>. If I<guardsize> is
greater
than zero, a guard area of at least size I<guardsize>
bytes is provided for each thread created with I<attr>.

A conforming implementation is permitted to round up
the value contained in I<guardsize> to a multiple
of the configurable system variable PAGESIZE (see
I<<sys/mman.h>>).
If an implementation rounds up the
value of I<guardsize> to a multiple of PAGESIZE, a call to
I<pthread_attr_getguardsize()>
specifying I<attr> will
store in the I<guardsize> parameter the guard size specified by the
previous
I<pthread_attr_setguardsize()>
function call.

The default value of the I<guardsize> attribute is PAGESIZE bytes.
The actual value of PAGESIZE is
implementation-dependent and may not be the same on all implementations.

If the I<stackaddr> attribute has been set (that is, the caller
is allocating and managing its own thread stacks), the
I<guardsize> attribute is ignored and no protection
will be provided by the implementation. It is the
responsibility of the application to manage stack overflow
along with stack allocation and management in this
case.

=head1 RETURN VALUE

If successful, the
I<pthread_attr_getguardsize()>
and
I<pthread_attr_setguardsize()>
functions return zero.
Otherwise, an error number is returned to indicate the error.


=head1 ERRORS

The
I<pthread_attr_getguardsize()>
and
I<pthread_attr_setguardsize()>
functions will fail if:

=over 4

=item [EINVAL]

The attribute I<attr> is invalid.

=item [EINVAL]

The parameter I<guardsize> is invalid.

=item [EINVAL]

The parameter I<guardsize> contains an invalid value.

=back

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

None.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<<pthread.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_attr_setinheritsched,> B<pthread_attr_getinheritsched>
- set and get inheritsched attribute
(B<REALTIME THREADS>)

=head1 SYNOPSIS

#include <pthread.h>

int pthread_attr_setinheritsched(pthread_attr_t *I<attr>,
int I<inheritsched>);
int pthread_attr_getinheritsched(const pthread_attr_t *I<attr>,
int *I<inheritsched>);

=head1 DESCRIPTION

The functions
I<pthread_attr_setinheritsched()>
and
I<pthread_attr_getinheritsched()>,
respectively, set and get the
I<inheritsched>
attribute in the
I<attr>
argument.

When the attribute objects are used by
I<pthread_create()>,
the
I<inheritsched>
attribute determines how the other scheduling attributes of
the created thread are to be set:

=over 4

=item PTHREAD_INHERIT_SCHED

Specifies that the scheduling policy and associated attributes
are to be inherited from the creating thread, and the scheduling
attributes in this
I<attr>
argument are to be ignored.

=item PTHREAD_EXPLICIT_SCHED

Specifies that the scheduling policy and associated attributes
are to be set to the corresponding values from this attribute object.

=back

The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED
are defined in the header
I<<pthread.h>>.

=head1 RETURN VALUE

If successful, the
I<pthread_attr_setinheritsched()>
and
I<pthread_attr_getinheritsched()>
functions return zero.
Otherwise, an error number is returned to indicate the error.

=head1 ERRORS

The
I<pthread_attr_setinheritsched()>
and
I<pthread_attr_getinheritsched()>
functions will fail if:

=over 4

=item [ENOSYS]

The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
implementation does not support the function.

=back

The
I<pthread_attr_setinheritsched()>
function may fail if:

=over 4

=item [EINVAL]

The value of the attribute being set is not valid.

=item [ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

=back

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

After these attributes have been set, a thread can be created with
the specified attributes using
I<pthread_create()>.
Using these routines does not affect the current running thread.

=head1 FUTURE DIRECTIONS

None.

=head1 SEE ALSO

I<pthread_attr_init()>,
I<pthread_attr_setscope()>,
I<pthread_attr_setschedpolicy()>,
I<pthread_attr_setschedparam()>,
I<pthread_create()>,
I<<pthread.h>>,
I<pthread_setschedparam()>,
I<<sched.h>>.

=head1 ______________________________________________________________________

=head1 NAME

B<pthread_attr_setschedparam,> B<pthread_attr_getschedparam>
- set and get schedparam attribute

=head1 SYNOPSIS

#include <pthread.h>

int pthread_attr_setschedparam(pthread_attr_t *I<attr>,
const struct sched_param *I<param>);
int pthread_attr_getschedparam(const pthread_attr_t *I<attr>,
struct sched_param *I<param>);

=head1 DESCRIPTION

The functions
I<pthread_attr_setschedparam()>
and
I<pthread_attr_getschedparam()>,
respectively, set and get the scheduling parameter
attributes in the
I<attr>
argument.
The contents of the
I<param>
structure are defined in
I<<sched.h>>.
For the SCHED_FIFO and SCHED_RR policies,
the only required member of
I<param>
is
I<sched_priority>.

=head1 RETURN VALUE

If successful, the
I<pthread_attr_setschedparam()>
and
I<pthread_attr_getschedparam()>
functions return zero.
Otherwise, an error number is returned to indicate the error.

=head1 ERRORS

The
I<pthread_attr_setschedparam()>
function may fail if:

=over 4

=item [EINVAL]

The value of the attribute being set is not valid.

=item [ENOTSUP]

An attempt was made to set the attribute to an unsupported value.

=back

The
I<pthread_attr_setschedparam()>
and
I<pthread_attr_getschedparam()>
functions will not return an error code of [EINTR].

=head1 EXAMPLES

None.

=head1 APPLICATION USAGE

After these attributes have been set, a thread can be created with
the specified attributes using